{"title":"MCP-Troubleshooting","slug":"troubleshooting","category":"mcp","summary":"Häufige MCP-Integrations-Probleme lösen — Server startet nicht, Tools erscheinen nicht, Auth-Fehler.","audience":["human","llm"],"tags":["mcp","troubleshooting","errors","debugging"],"difficulty":"intermediate","updated":"2026-06-27","word_count":499,"read_minutes":2,"llm_context":"Common issues:\n1. Node.js < 18 → upgrade to 18+\n2. Mind Key invalid → check format (mk_...), get fresh via POST /minds\n3. npx not found → install Node.js\n4. Tools not appearing → restart client, check config JSON validity\n5. SYNAPSE_URL unreachable → curl /health to verify\n6. MCP server crashes → check logs, run npx manually to see error\nDebug steps: run `npx -y synapse-mcp-api@latest` manually, check stderr\nLogs: Claude Desktop ~/Library/Logs/Claude/mcp.log, Cursor ~/.cursor/logs/\n","lang":"de","translated":true,"requested_lang":"de","content_markdown":"\n# MCP-Troubleshooting\n\nHäufige Probleme und Lösungen bei der Integration von Synapse MCP mit deinem\nLLM-Client.\n\n## Schnelle Diagnose-Checkliste\n\n1. ✅ Node.js 18+ installiert? (`node --version`)\n2. ✅ Mind Key beginnt mit `mk_`? (nicht JWT `eyJ...`)\n3. ✅ Synapse-API erreichbar? (`curl https://synapse.schaefer.zone/health`)\n4. ✅ Mind Key funktioniert? (`curl -H \"Authorization: Bearer mk_...\" .../memory/recall`)\n5. ✅ Config-Datei ist valides JSON? (keine Trailing-Commas, keine Kommentare)\n6. ✅ Client nach Config-Änderung neu gestartet?\n7. ✅ MCP-Server startet manuell? (`npx -y synapse-mcp-api@latest`)\n\n## Problem: Keine Tools im Client sichtbar\n\n### Symptome\n\n- Claude Desktop / Cursor / Continue zeigt 0 Tools\n- Kein 🔌-Icon oder „synapse\"-Eintrag in MCP-Server-Liste\n\n### Lösungen\n\n1. **Client vollständig neu starten** — Cmd+Q auf macOS (nicht nur Fenster schließen)\n2. **Config-Datei-Ort prüfen**:\n - Claude Desktop macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`\n - Claude Desktop Windows: `%APPDATA%\\Claude\\claude_desktop_config.json`\n - Cursor: `~/.cursor/config.json`\n - Continue: `~/.continue/config.json`\n3. **JSON validieren** — Config in einfügen\n4. **Client-Logs auf MCP-Fehler prüfen**:\n - Claude Desktop: `~/Library/Logs/Claude/mcp.log` (macOS)\n - Cursor: View → Output → MCP\n5. **MCP-Server manuell ausführen**, um Startup-Fehler zu sehen:\n ```bash\n SYNAPSE_MIND_KEY=mk_... npx -y synapse-mcp-api@latest\n ```\n\n## Problem: „Mind Key invalid\"-Fehler\n\n### Symptome\n\n- Tools erscheinen, aber Aufrufe schlagen mit „401 Unauthorized\" fehl\n- Fehler: „Mind Key fehlt oder ungültig\"\n\n### Lösungen\n\n1. **Mind-Key-Format verifizieren** — beginnt mit `mk_`, ~40 Zeichen\n2. **Direkt testen**:\n ```bash\n curl -H \"Authorization: Bearer mk_YOUR_KEY\" \\\n https://synapse.schaefer.zone/memory/recall\n ```\n3. **Env-Var gesetzt prüfen** — für stdio-Transport muss die Env-Var in der\n MCP-Server-Config stehen, nicht in deiner Shell\n4. **Frischen Mind Key holen**:\n ```bash\n # Login to get JWT\n curl -X POST .../login -d '{\"email\":\"...\",\"password\":\"...\"}'\n # Create new mind\n curl -X POST .../minds -H \"Authorization: Bearer YOUR_JWT\" -d '{\"name\":\"new mind\"}'\n ```\n\n## Problem: npx nicht gefunden\n\n### Symptome\n\n- Fehler: „npx: command not found\"\n- MCP-Server startet nicht\n\n### Lösungen\n\n1. **Node.js 18+ installieren**:\n - macOS: `brew install node` oder von herunterladen\n - Linux: `curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - && sudo apt install -y nodejs`\n - Windows: von herunterladen\n2. **Nach Installation Terminal neu starten**\n3. **Verifizieren**: `node --version && npx --version`\n\n## Problem: SYNAPSE_URL nicht erreichbar\n\n### Symptome\n\n- MCP-Server startet, aber Tool-Aufrufe timen aus\n- Fehler: „fetch failed\" oder „ECONNREFUSED\"\n\n### Lösungen\n\n1. **Verbindbarkeit testen**:\n ```bash\n curl https://synapse.schaefer.zone/health\n ```\n2. **Corporate-Firewall prüfen** — könnte ausgehendes HTTPS blockieren\n3. **Alternative URL versuchen**:\n - Produktion: `https://synapse.schaefer.zone`\n - MCP-Server: `https://synapse-mcp.schaefer.zone`\n4. **Für Self-Hosted**: sicherstellen, dass deine Synapse-Instanz läuft und erreichbar ist\n\n## Problem: MCP-Server crasht\n\n### Symptome\n\n- MCP-Server beendet sich sofort nach Start\n- Client-Logs zeigen „MCP server disconnected\"\n\n### Lösungen\n\n1. **Manuell ausführen, um Fehler zu sehen**:\n ```bash\n SYNAPSE_MIND_KEY=mk_... SYNAPSE_URL=https://synapse.schaefer.zone \\\n npx -y synapse-mcp-api@latest\n ```\n2. **Port-Konflikte prüfen** — MCP-Server nutzt standardmäßig Port 13100\n3. **npx-Cache leeren**:\n ```bash\n npx clear-npx-cache\n # or\n rm -rf ~/.npm/_npx\n ```\n4. **Auf neueste Version updaten**:\n ```bash\n npx -y synapse-mcp-api@latest --version\n ```\n\n## Problem: Tool-Aufrufe liefern 429\n\n### Symptome\n\n- Fehler: „Rate limit exceeded\"\n\n### Lösungen\n\nDas sollte mit MCP nicht passieren (verwendet Header-Auth, kein Rate Limit).\nFalls doch:\n\n1. **Prüfen, ob du irgendwo `?key=` verwendest** — auf Header-Auth wechseln\n2. **`SYNAPSE_URL` verifizieren** — sicherstellen, dass sie auf die richtige Instanz zeigt\n3. **Support kontaktieren**, falls das Problem besteht\n\n## Problem: Tools erscheinen, funktionieren aber nicht\n\n### Symptome\n\n- Tools im Client gelistet\n- Tool-Aufruf liefert Fehler oder kein Ergebnis\n\n### Lösungen\n\n1. **Tool-Name prüfen** — muss exakt sein (z. B. `memory_recall`, nicht `memory.recall`)\n2. **Argumente verifizieren** — Input-Schema des Tools prüfen\n3. **Via direkter API testen**:\n ```bash\n curl -X POST https://synapse.schaefer.zone/memory \\\n -H \"Authorization: Bearer mk_...\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"category\":\"fact\",\"key\":\"test\",\"content\":\"hello\"}'\n ```\n4. **Synapse-Health prüfen**:\n ```bash\n curl https://synapse.schaefer.zone/health\n ```\n\n## Hilfe holen\n\nFalls nichts davon dein Problem löst:\n\n1. **Bestehende Issues prüfen**: \n2. **Neues Issue öffnen** mit:\n - MCP-Server-Version (`npx -y synapse-mcp-api@latest --version`)\n - Client-Name und -Version\n - Betriebssystem\n - Relevante Log-Auszüge\n - Reproduktionsschritte\n\n## Nächste Schritte\n\n- [Claude-Desktop-Setup](/docs/mcp/claude-desktop)\n- [Claude-Code-Setup](/docs/mcp/claude-code)\n- [API-Errors](/docs/api/errors)\n","content_html":"

MCP-Troubleshooting

\n

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

\n

Schnelle Diagnose-Checkliste

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

Problem: Keine Tools im Client sichtbar

\n

Symptome

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

Lösungen

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

Problem: „Mind Key invalid"-Fehler

\n

Symptome

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

Lösungen

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

Problem: npx nicht gefunden

\n

Symptome

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

Lösungen

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

Problem: SYNAPSE_URL nicht erreichbar

\n

Symptome

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

Lösungen

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

Problem: MCP-Server crasht

\n

Symptome

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

Lösungen

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

Problem: Tool-Aufrufe liefern 429

\n

Symptome

\n
    \n
  • Fehler: „Rate limit exceeded"
    • \n
\n

Lösungen

\n

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

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

Problem: Tools erscheinen, funktionieren aber nicht

\n

Symptome

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

Lösungen

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

Hilfe holen

\n

Falls nichts davon dein Problem löst:

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

Nächste Schritte

\n\n","urls":{"html":"/docs/mcp/troubleshooting","text":"/docs/mcp/troubleshooting?format=text","json":"/docs/mcp/troubleshooting?format=json","llm":"/docs/mcp/troubleshooting?format=llm"},"translations_available":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"]}