# MCP-Troubleshooting
SUMMARY: Häufige MCP-Integrations-Probleme lösen — Server startet nicht, Tools erscheinen nicht, Auth-Fehler.

KEY CONTEXT:
Common issues:
1. Node.js < 18 → upgrade to 18+
2. Mind Key invalid → check format (mk_...), get fresh via POST /minds
3. npx not found → install Node.js
4. Tools not appearing → restart client, check config JSON validity
5. SYNAPSE_URL unreachable → curl /health to verify
6. MCP server crashes → check logs, run npx manually to see error
Debug steps: run `npx -y synapse-mcp-api@latest` manually, check stderr
Logs: Claude Desktop ~/Library/Logs/Claude/mcp.log, Cursor ~/.cursor/logs/

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? ()
2. ✅ Mind Key beginnt mit ? (nicht JWT )
3. ✅ Synapse-API erreichbar? ()
4. ✅ Mind Key funktioniert? ()
5. ✅ Config-Datei ist valides JSON? (keine Trailing-Commas, keine Kommentare)
6. ✅ Client nach Config-Änderung neu gestartet?
7. ✅ MCP-Server startet manuell? ()
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: 
   - Claude Desktop Windows: 
   - Cursor: 
   - Continue: 
3. JSON validieren — Config in <https://jsonlint.com> einfügen
4. Client-Logs auf MCP-Fehler prüfen:
   - Claude Desktop:  (macOS)
   - Cursor: View → Output → MCP
5. MCP-Server manuell ausführen, um Startup-Fehler zu sehen:
   [CODE BLOCK]
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 , 40 Zeichen
2. Direkt testen:
   [CODE BLOCK]
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:
   [CODE BLOCK]
Problem: npx nicht gefunden
Symptome
- Fehler: „npx: command not found"
- MCP-Server startet nicht
Lösungen
1. Node.js 18+ installieren:
   - macOS:  oder von <https://nodejs.org> herunterladen
   - Linux: 
   - Windows: von <https://nodejs.org> herunterladen
2. Nach Installation Terminal neu starten
3. Verifizieren: 
Problem: SYNAPSEURL nicht erreichbar
Symptome
- MCP-Server startet, aber Tool-Aufrufe timen aus
- Fehler: „fetch failed" oder „ECONNREFUSED"
Lösungen
1. Verbindbarkeit testen:
   [CODE BLOCK]
2. Corporate-Firewall prüfen — könnte ausgehendes HTTPS blockieren
3. Alternative URL versuchen:
   - Produktion: 
   - MCP-Server: 
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:
   [CODE BLOCK]
2. Port-Konflikte prüfen — MCP-Server nutzt standardmäßig Port 13100
3. npx-Cache leeren:
   [CODE BLOCK]
4. Auf neueste Version updaten:
   [CODE BLOCK]
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  verwendest — auf Header-Auth wechseln
2.  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. , nicht )
2. Argumente verifizieren — Input-Schema des Tools prüfen
3. Via direkter API testen:
   [CODE BLOCK]
4. Synapse-Health prüfen:
   [CODE BLOCK]
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 ()
   - Client-Name und -Version
   - Betriebssystem
   - Relevante Log-Auszüge
   - Reproduktionsschritte
Nächste Schritte
- Claude-Desktop-Setup
- Claude-Code-Setup
- API-Errors