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:

   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:

   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:

   # 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:

   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:

   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:

   npx clear-npx-cache
   # or
   rm -rf ~/.npm/_npx

4. Auf neueste Version updaten:

   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:

   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:

   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
• Claude-Code-Setup
• API-Errors