# MCP-Troubleshooting

Häufige Probleme und Lösungen bei der Integration von Synapse MCP mit deinem
LLM-Client.

## Schnelle Diagnose-Checkliste

1. ✅ Node.js 18+ installiert? (`node --version`)
2. ✅ Mind Key beginnt mit `mk_`? (nicht JWT `eyJ...`)
3. ✅ Synapse-API erreichbar? (`curl https://synapse.schaefer.zone/health`)
4. ✅ Mind Key funktioniert? (`curl -H "Authorization: Bearer mk_..." .../memory/recall`)
5. ✅ Config-Datei ist valides JSON? (keine Trailing-Commas, keine Kommentare)
6. ✅ Client nach Config-Änderung neu gestartet?
7. ✅ MCP-Server startet manuell? (`npx -y synapse-mcp-api@latest`)

## Problem: Keine Tools im Client sichtbar

### Symptome

- Claude Desktop / Cursor / Continue zeigt 0 Tools
- Kein 🔌-Icon oder „synapse"-Eintrag in MCP-Server-Liste

### Lösungen

1. **Client vollständig neu starten** — Cmd+Q auf macOS (nicht nur Fenster schließen)
2. **Config-Datei-Ort prüfen**:
   - Claude Desktop macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
   - Claude Desktop Windows: `%APPDATA%\Claude\claude_desktop_config.json`
   - Cursor: `~/.cursor/config.json`
   - Continue: `~/.continue/config.json`
3. **JSON validieren** — Config in <https://jsonlint.com> einfügen
4. **Client-Logs auf MCP-Fehler prüfen**:
   - Claude Desktop: `~/Library/Logs/Claude/mcp.log` (macOS)
   - Cursor: View → Output → MCP
5. **MCP-Server manuell ausführen**, um Startup-Fehler zu sehen:
   ```bash
   SYNAPSE_MIND_KEY=mk_... npx -y synapse-mcp-api@latest
   ```

## Problem: „Mind Key invalid"-Fehler

### Symptome

- Tools erscheinen, aber Aufrufe schlagen mit „401 Unauthorized" fehl
- Fehler: „Mind Key fehlt oder ungültig"

### Lösungen

1. **Mind-Key-Format verifizieren** — beginnt mit `mk_`, ~40 Zeichen
2. **Direkt testen**:
   ```bash
   curl -H "Authorization: Bearer mk_YOUR_KEY" \
        https://synapse.schaefer.zone/memory/recall
   ```
3. **Env-Var gesetzt prüfen** — für stdio-Transport muss die Env-Var in der
   MCP-Server-Config stehen, nicht in deiner Shell
4. **Frischen Mind Key holen**:
   ```bash
   # Login to get JWT
   curl -X POST .../login -d '{"email":"...","password":"..."}'
   # Create new mind
   curl -X POST .../minds -H "Authorization: Bearer YOUR_JWT" -d '{"name":"new mind"}'
   ```

## Problem: npx nicht gefunden

### Symptome

- Fehler: „npx: command not found"
- MCP-Server startet nicht

### Lösungen

1. **Node.js 18+ installieren**:
   - macOS: `brew install node` oder von <https://nodejs.org> herunterladen
   - Linux: `curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - && sudo apt install -y nodejs`
   - Windows: von <https://nodejs.org> herunterladen
2. **Nach Installation Terminal neu starten**
3. **Verifizieren**: `node --version && npx --version`

## Problem: SYNAPSE_URL nicht erreichbar

### Symptome

- MCP-Server startet, aber Tool-Aufrufe timen aus
- Fehler: „fetch failed" oder „ECONNREFUSED"

### Lösungen

1. **Verbindbarkeit testen**:
   ```bash
   curl https://synapse.schaefer.zone/health
   ```
2. **Corporate-Firewall prüfen** — könnte ausgehendes HTTPS blockieren
3. **Alternative URL versuchen**:
   - Produktion: `https://synapse.schaefer.zone`
   - MCP-Server: `https://synapse-mcp.schaefer.zone`
4. **Für Self-Hosted**: sicherstellen, dass deine Synapse-Instanz läuft und erreichbar ist

## Problem: MCP-Server crasht

### Symptome

- MCP-Server beendet sich sofort nach Start
- Client-Logs zeigen „MCP server disconnected"

### Lösungen

1. **Manuell ausführen, um Fehler zu sehen**:
   ```bash
   SYNAPSE_MIND_KEY=mk_... SYNAPSE_URL=https://synapse.schaefer.zone \
     npx -y synapse-mcp-api@latest
   ```
2. **Port-Konflikte prüfen** — MCP-Server nutzt standardmäßig Port 13100
3. **npx-Cache leeren**:
   ```bash
   npx clear-npx-cache
   # or
   rm -rf ~/.npm/_npx
   ```
4. **Auf neueste Version updaten**:
   ```bash
   npx -y synapse-mcp-api@latest --version
   ```

## Problem: Tool-Aufrufe liefern 429

### Symptome

- Fehler: „Rate limit exceeded"

### Lösungen

Das sollte mit MCP nicht passieren (verwendet Header-Auth, kein Rate Limit).
Falls doch:

1. **Prüfen, ob du irgendwo `?key=` verwendest** — auf Header-Auth wechseln
2. **`SYNAPSE_URL` verifizieren** — sicherstellen, dass sie auf die richtige Instanz zeigt
3. **Support kontaktieren**, falls das Problem besteht

## Problem: Tools erscheinen, funktionieren aber nicht

### Symptome

- Tools im Client gelistet
- Tool-Aufruf liefert Fehler oder kein Ergebnis

### Lösungen

1. **Tool-Name prüfen** — muss exakt sein (z. B. `memory_recall`, nicht `memory.recall`)
2. **Argumente verifizieren** — Input-Schema des Tools prüfen
3. **Via direkter API testen**:
   ```bash
   curl -X POST https://synapse.schaefer.zone/memory \
     -H "Authorization: Bearer mk_..." \
     -H "Content-Type: application/json" \
     -d '{"category":"fact","key":"test","content":"hello"}'
   ```
4. **Synapse-Health prüfen**:
   ```bash
   curl https://synapse.schaefer.zone/health
   ```

## Hilfe holen

Falls nichts davon dein Problem löst:

1. **Bestehende Issues prüfen**: <https://gitlab.com/schaefer-services/synapse-mcp/-/issues>
2. **Neues Issue öffnen** mit:
   - MCP-Server-Version (`npx -y synapse-mcp-api@latest --version`)
   - Client-Name und -Version
   - Betriebssystem
   - Relevante Log-Auszüge
   - Reproduktionsschritte

## Nächste Schritte

- [Claude-Desktop-Setup](/docs/mcp/claude-desktop)
- [Claude-Code-Setup](/docs/mcp/claude-code)
- [API-Errors](/docs/api/errors)