# MCP-probleemoplossing
SUMMARY: Los veelvoorkomende MCP-integratieproblemen op — server start niet, tools verschijnen niet, auth-fouten.

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-probleemoplossing
Veelvoorkomende problemen en oplossingen bij het integreren van Synapse MCP met uw LLM-client.
Snelle diagnosecontrole
1. ✅ Node.js 18+ geïnstalleerd? ()
2. ✅ Mind Key begint met ? (niet JWT )
3. ✅ Synapse-API bereikbaar? ()
4. ✅ Mind Key werkt? ()
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? ()
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: 
   - Claude Desktop Windows: 
   - Cursor: 
   - Continue: 
3. Valideer de JSON — plak de configuratie in <https://jsonlint.com>
4. Controleer de client-logs op MCP-fouten:
   - Claude Desktop:  (macOS)
   - Cursor: View → Output → MCP
5. Start de MCP-server handmatig om opstartfouten te zien:
   [CODE BLOCK]
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 , ongeveer 40 tekens
2. Test direct:
   [CODE BLOCK]
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:
   [CODE BLOCK]
Probleem: npx niet gevonden
Symptomen
- Foutmelding: "npx: command not found"
- MCP-server start niet
Oplossingen
1. Installeer Node.js 18+:
   - macOS:  of download via <https://nodejs.org>
   - Linux: 
   - Windows: download via <https://nodejs.org>
2. Herstart de terminal na installatie
3. Verifieer: 
Probleem: SYNAPSEURL onbereikbaar
Symptomen
- MCP-server start, maar tool-aanroepen time-out
- Foutmelding: "fetch failed" of "ECONNREFUSED"
Oplossingen
1. Test de verbinding:
   [CODE BLOCK]
2. Controleer de bedrijfsfirewall — blokkeert mogelijk uitgaand HTTPS-verkeer
3. Probeer een alternatieve URL:
   - Productie: 
   - MCP-server: 
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:
   [CODE BLOCK]
2. Controleer op poortconflicten — de MCP-server gebruikt standaard poort 13100
3. Wis de npx-cache:
   [CODE BLOCK]
4. Werk bij naar de laatste versie:
   [CODE BLOCK]
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  gebruikt — schakel over op header-auth
2. Verifieer  — 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. , niet )
2. Verifieer de argumenten — controleer het inputschema van de tool
3. Test via de directe API:
   [CODE BLOCK]
4. Controleer de gezondheid van Synapse:
   [CODE BLOCK]
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 ()
   - Naam en versie van de client
   - Besturingssysteem
   - Relevante logfragmenten
   - Stappen om te reproduceren
Volgende stappen
- Claude Desktop-instellatie
- Claude Code-instellatie
- API-fouten