MCP-probleemoplossing

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

Snelle diagnosecontrole

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

Probleem: er verschijnen geen tools in de client

Symptomen

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

Oplossingen

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

   SYNAPSE_MIND_KEY=mk_... npx -y synapse-mcp-api@latest

Probleem: foutmelding "Mind Key invalid"

Symptomen

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

Oplossingen

1. Verifieer het formaat van de Mind Key — begint met mk_, ongeveer 40 tekens
2. Test direct:

   curl -H "Authorization: Bearer mk_YOUR_KEY" \
        https://synapse.schaefer.zone/memory/recall

3. Controleer of de omgevingsvariabele is ingesteld — voor stdio-transport moet de omgevingsvariabele in de MCP-serverconfiguratie staan, niet in uw shell
4. Vraag een nieuwe Mind Key aan:

   # 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"}'

Probleem: npx niet gevonden

Symptomen

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

Oplossingen

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

Probleem: SYNAPSE_URL onbereikbaar

Symptomen

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

Oplossingen

1. Test de verbinding:

   curl https://synapse.schaefer.zone/health

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

Probleem: MCP-server crasht

Symptomen

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

Oplossingen

1. Voer handmatig uit om de fout te zien:

   SYNAPSE_MIND_KEY=mk_... SYNAPSE_URL=https://synapse.schaefer.zone \
     npx -y synapse-mcp-api@latest

2. Controleer op poortconflicten — de MCP-server gebruikt standaard poort 13100
3. Wis de npx-cache:

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

4. Werk bij naar de laatste versie:

   npx -y synapse-mcp-api@latest --version

Probleem: tool-aanroepen retourneren 429

Symptomen

• Foutmelding: "Rate limit exceeded"

Oplossingen

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

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

Probleem: tools verschijnen, maar werken niet

Symptomen

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

Oplossingen

1. Controleer de toolnaam — moet exact kloppen (bijv. memory_recall, niet memory.recall)
2. Verifieer de argumenten — controleer het inputschema van de tool
3. Test via de directe API:

   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. Controleer de gezondheid van Synapse:

   curl https://synapse.schaefer.zone/health

Hulp krijgen

Als geen van de bovenstaande oplossingen uw probleem verhelpt:

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

Volgende stappen

• Claude Desktop-instellatie
• Claude Code-instellatie
• API-fouten