{"title":"MCP-probleemoplossing","slug":"troubleshooting","category":"mcp","summary":"Los veelvoorkomende MCP-integratieproblemen op — server start niet, tools verschijnen niet, auth-fouten.","audience":["human","llm"],"tags":["mcp","troubleshooting","errors","debugging"],"difficulty":"intermediate","updated":"2026-06-27","word_count":568,"read_minutes":3,"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":"nl","translated":true,"requested_lang":"nl","content_markdown":"\n# MCP-probleemoplossing\n\nVeelvoorkomende problemen en oplossingen bij het integreren van Synapse MCP met uw LLM-client.\n\n## Snelle diagnosecontrole\n\n1. ✅ Node.js 18+ geïnstalleerd? (`node --version`)\n2. ✅ Mind Key begint met `mk_`? (niet JWT `eyJ...`)\n3. ✅ Synapse-API bereikbaar? (`curl https://synapse.schaefer.zone/health`)\n4. ✅ Mind Key werkt? (`curl -H \"Authorization: Bearer mk_...\" .../memory/recall`)\n5. ✅ Config-bestand is geldige JSON? (geen komma's aan het einde, geen opmerkingen)\n6. ✅ Client herstart na config-wijziging?\n7. ✅ MCP-server start handmatig? (`npx -y synapse-mcp-api@latest`)\n\n## Probleem: er verschijnen geen tools in de client\n\n### Symptomen\n\n- Claude Desktop / Cursor / Continue toont 0 tools\n- Geen 🔌-icoon of \"synapse\"-vermelding in de lijst met MCP-servers\n\n### Oplossingen\n\n1. **Start de client volledig opnieuw** — Cmd+Q op macOS (niet alleen het venster sluiten)\n2. **Controleer de locatie van het config-bestand**:\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. **Valideer de JSON** — plak de configuratie in \n4. **Controleer de client-logs** op MCP-fouten:\n - Claude Desktop: `~/Library/Logs/Claude/mcp.log` (macOS)\n - Cursor: View → Output → MCP\n5. **Start de MCP-server handmatig** om opstartfouten te zien:\n ```bash\n SYNAPSE_MIND_KEY=mk_... npx -y synapse-mcp-api@latest\n ```\n\n## Probleem: foutmelding \"Mind Key invalid\"\n\n### Symptomen\n\n- Tools verschijnen, maar aanroepen mislukken met \"401 Unauthorized\"\n- Foutmelding: \"Mind Key fehlt oder ungültig\"\n\n### Oplossingen\n\n1. **Verifieer het formaat van de Mind Key** — begint met `mk_`, ongeveer 40 tekens\n2. **Test direct**:\n ```bash\n curl -H \"Authorization: Bearer mk_YOUR_KEY\" \\\n https://synapse.schaefer.zone/memory/recall\n ```\n3. **Controleer of de omgevingsvariabele is ingesteld** — voor stdio-transport moet de omgevingsvariabele in de MCP-serverconfiguratie staan, niet in uw shell\n4. **Vraag een nieuwe Mind Key aan**:\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## Probleem: npx niet gevonden\n\n### Symptomen\n\n- Foutmelding: \"npx: command not found\"\n- MCP-server start niet\n\n### Oplossingen\n\n1. **Installeer Node.js 18+**:\n - macOS: `brew install node` of download via \n - Linux: `curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - && sudo apt install -y nodejs`\n - Windows: download via \n2. **Herstart de terminal** na installatie\n3. **Verifieer**: `node --version && npx --version`\n\n## Probleem: SYNAPSE_URL onbereikbaar\n\n### Symptomen\n\n- MCP-server start, maar tool-aanroepen time-out\n- Foutmelding: \"fetch failed\" of \"ECONNREFUSED\"\n\n### Oplossingen\n\n1. **Test de verbinding**:\n ```bash\n curl https://synapse.schaefer.zone/health\n ```\n2. **Controleer de bedrijfsfirewall** — blokkeert mogelijk uitgaand HTTPS-verkeer\n3. **Probeer een alternatieve URL**:\n - Productie: `https://synapse.schaefer.zone`\n - MCP-server: `https://synapse-mcp.schaefer.zone`\n4. **Voor self-hosted**: zorg dat uw Synapse-instantie draait en bereikbaar is\n\n## Probleem: MCP-server crasht\n\n### Symptomen\n\n- MCP-server sluit direct na het opstarten af\n- Client-logs tonen \"MCP server disconnected\"\n\n### Oplossingen\n\n1. **Voer handmatig uit om de fout te zien**:\n ```bash\n SYNAPSE_MIND_KEY=mk_... SYNAPSE_URL=https://synapse.schaefer.zone \\\n npx -y synapse-mcp-api@latest\n ```\n2. **Controleer op poortconflicten** — de MCP-server gebruikt standaard poort 13100\n3. **Wis de npx-cache**:\n ```bash\n npx clear-npx-cache\n # or\n rm -rf ~/.npm/_npx\n ```\n4. **Werk bij naar de laatste versie**:\n ```bash\n npx -y synapse-mcp-api@latest --version\n ```\n\n## Probleem: tool-aanroepen retourneren 429\n\n### Symptomen\n\n- Foutmelding: \"Rate limit exceeded\"\n\n### Oplossingen\n\nDit zou niet moeten voorkomen met MCP (gebruikt header-auth, geen rate limit). Mocht het toch voorkomen:\n\n1. **Controleer of u ergens `?key=` gebruikt** — schakel over op header-auth\n2. **Verifieer `SYNAPSE_URL`** — zorg dat deze naar de juiste instantie wijst\n3. **Neem contact op met support** als het probleem aanhoudt\n\n## Probleem: tools verschijnen, maar werken niet\n\n### Symptomen\n\n- Tools worden in de client getoond\n- Een tool aanroepen levert een foutmelding of geen resultaat op\n\n### Oplossingen\n\n1. **Controleer de toolnaam** — moet exact kloppen (bijv. `memory_recall`, niet `memory.recall`)\n2. **Verifieer de argumenten** — controleer het inputschema van de tool\n3. **Test via de directe API**:\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. **Controleer de gezondheid van Synapse**:\n ```bash\n curl https://synapse.schaefer.zone/health\n ```\n\n## Hulp krijgen\n\nAls geen van de bovenstaande oplossingen uw probleem verhelpt:\n\n1. **Controleer bestaande issues**: \n2. **Open een nieuw issue** met:\n - MCP-serverversie (`npx -y synapse-mcp-api@latest --version`)\n - Naam en versie van de client\n - Besturingssysteem\n - Relevante logfragmenten\n - Stappen om te reproduceren\n\n## Volgende stappen\n\n- [Claude Desktop-instellatie](/docs/mcp/claude-desktop)\n- [Claude Code-instellatie](/docs/mcp/claude-code)\n- [API-fouten](/docs/api/errors)\n","content_html":"

MCP-probleemoplossing

\n

Veelvoorkomende problemen en oplossingen bij het integreren van Synapse MCP met uw LLM-client.

\n

Snelle diagnosecontrole

\n
    \n
  1. ✅ Node.js 18+ geïnstalleerd? (node --version)
    2. \n
  2. ✅ Mind Key begint met mk_? (niet JWT eyJ...)
    3. \n
  3. ✅ Synapse-API bereikbaar? (curl https://synapse.schaefer.zone/health)
    4. \n
  4. ✅ Mind Key werkt? (curl -H "Authorization: Bearer mk_..." .../memory/recall)
    5. \n
  5. ✅ Config-bestand is geldige JSON? (geen komma's aan het einde, geen opmerkingen)
    6. \n
  6. ✅ Client herstart na config-wijziging?
    7. \n
  7. ✅ MCP-server start handmatig? (npx -y synapse-mcp-api@latest)
    8. \n
\n

Probleem: er verschijnen geen tools in de client

\n

Symptomen

\n
    \n
  • Claude Desktop / Cursor / Continue toont 0 tools
    • \n
  • Geen 🔌-icoon of "synapse"-vermelding in de lijst met MCP-servers
    • \n
\n

Oplossingen

\n
    \n
  1. Start de client volledig opnieuw — Cmd+Q op macOS (niet alleen het venster sluiten)
    2. \n
  2. Controleer de locatie van het config-bestand:
      \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. Valideer de JSON — plak de configuratie in https://jsonlint.com
    4. \n
  4. Controleer de client-logs op MCP-fouten:
      \n
    • Claude Desktop: ~/Library/Logs/Claude/mcp.log (macOS)
      • \n
    • Cursor: View → Output → MCP
      • \n
    \n
    5. \n
  5. Start de MCP-server handmatig om opstartfouten te zien:
    SYNAPSE_MIND_KEY=mk_... npx -y synapse-mcp-api@latest
    6. \n
\n

Probleem: foutmelding "Mind Key invalid"

\n

Symptomen

\n
    \n
  • Tools verschijnen, maar aanroepen mislukken met "401 Unauthorized"
    • \n
  • Foutmelding: "Mind Key fehlt oder ungültig"
    • \n
\n

Oplossingen

\n
    \n
  1. Verifieer het formaat van de Mind Key — begint met mk_, ongeveer 40 tekens
    2. \n
  2. Test direct:
    curl -H "Authorization: Bearer mk_YOUR_KEY" \\\n     https://synapse.schaefer.zone/memory/recall
    3. \n
  3. Controleer of de omgevingsvariabele is ingesteld — voor stdio-transport moet de omgevingsvariabele in de MCP-serverconfiguratie staan, niet in uw shell
    4. \n
  4. Vraag een nieuwe Mind Key aan:
    # 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

Probleem: npx niet gevonden

\n

Symptomen

\n
    \n
  • Foutmelding: "npx: command not found"
    • \n
  • MCP-server start niet
    • \n
\n

Oplossingen

\n
    \n
  1. Installeer Node.js 18+:
      \n
    • macOS: brew install node of download via https://nodejs.org
      • \n
    • Linux: curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - && sudo apt install -y nodejs
      • \n
    • Windows: download via https://nodejs.org
      • \n
    \n
    2. \n
  2. Herstart de terminal na installatie
    3. \n
  3. Verifieer: node --version && npx --version
    4. \n
\n

Probleem: SYNAPSE_URL onbereikbaar

\n

Symptomen

\n
    \n
  • MCP-server start, maar tool-aanroepen time-out
    • \n
  • Foutmelding: "fetch failed" of "ECONNREFUSED"
    • \n
\n

Oplossingen

\n
    \n
  1. Test de verbinding:
    curl https://synapse.schaefer.zone/health
    2. \n
  2. Controleer de bedrijfsfirewall — blokkeert mogelijk uitgaand HTTPS-verkeer
    3. \n
  3. Probeer een alternatieve URL:
      \n
    • Productie: https://synapse.schaefer.zone
      • \n
    • MCP-server: https://synapse-mcp.schaefer.zone
      • \n
    \n
    4. \n
  4. Voor self-hosted: zorg dat uw Synapse-instantie draait en bereikbaar is
    5. \n
\n

Probleem: MCP-server crasht

\n

Symptomen

\n
    \n
  • MCP-server sluit direct na het opstarten af
    • \n
  • Client-logs tonen "MCP server disconnected"
    • \n
\n

Oplossingen

\n
    \n
  1. Voer handmatig uit om de fout te zien:
    SYNAPSE_MIND_KEY=mk_... SYNAPSE_URL=https://synapse.schaefer.zone \\\n  npx -y synapse-mcp-api@latest
    2. \n
  2. Controleer op poortconflicten — de MCP-server gebruikt standaard poort 13100
    3. \n
  3. Wis de npx-cache:
    npx clear-npx-cache\n# or\nrm -rf ~/.npm/_npx
    4. \n
  4. Werk bij naar de laatste versie:
    npx -y synapse-mcp-api@latest --version
    5. \n
\n

Probleem: tool-aanroepen retourneren 429

\n

Symptomen

\n
    \n
  • Foutmelding: "Rate limit exceeded"
    • \n
\n

Oplossingen

\n

Dit zou niet moeten voorkomen met MCP (gebruikt header-auth, geen rate limit). Mocht het toch voorkomen:

\n
    \n
  1. Controleer of u ergens ?key= gebruikt — schakel over op header-auth
    2. \n
  2. Verifieer SYNAPSE_URL — zorg dat deze naar de juiste instantie wijst
    3. \n
  3. Neem contact op met support als het probleem aanhoudt
    4. \n
\n

Probleem: tools verschijnen, maar werken niet

\n

Symptomen

\n
    \n
  • Tools worden in de client getoond
    • \n
  • Een tool aanroepen levert een foutmelding of geen resultaat op
    • \n
\n

Oplossingen

\n
    \n
  1. Controleer de toolnaam — moet exact kloppen (bijv. memory_recall, niet memory.recall)
    2. \n
  2. Verifieer de argumenten — controleer het inputschema van de tool
    3. \n
  3. Test via de directe API:
    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. Controleer de gezondheid van Synapse:
    curl https://synapse.schaefer.zone/health
    5. \n
\n

Hulp krijgen

\n

Als geen van de bovenstaande oplossingen uw probleem verhelpt:

\n
    \n
  1. Controleer bestaande issues: https://gitlab.com/schaefer-services/synapse-mcp/-/issues
    2. \n
  2. Open een nieuw issue met:
      \n
    • MCP-serverversie (npx -y synapse-mcp-api@latest --version)
      • \n
    • Naam en versie van de client
      • \n
    • Besturingssysteem
      • \n
    • Relevante logfragmenten
      • \n
    • Stappen om te reproduceren
      • \n
    \n
    3. \n
\n

Volgende stappen

\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"]}