Dépannage MCP

Problèmes courants et solutions lors de l'intégration de MCP Synapse avec votre client LLM.

Liste de vérification de diagnostic rapide

1. ✅ Node.js 18+ installé ? (node --version)
2. ✅ La Mind Key commence par mk_ ? (pas un JWT eyJ...)
3. ✅ L'API Synapse est accessible ? (curl https://synapse.schaefer.zone/health)
4. ✅ La Mind Key fonctionne ? (curl -H "Authorization: Bearer mk_..." .../memory/recall)
5. ✅ Le fichier de config est du JSON valide ? (pas de virgules finales, pas de commentaires)
6. ✅ Le client a-t-il été redémarré après le changement de config ?
7. ✅ Le serveur MCP démarre-t-il manuellement ? (npx -y synapse-mcp-api@latest)

Problème : aucun outil n'apparaît dans le client

Symptômes

• Claude Desktop / Cursor / Continue affiche 0 outils
• Pas d'icône 🔌 ou d'entrée « synapse » dans la liste des serveurs MCP

Solutions

1. Redémarrez le client complètement — Cmd+Q sur macOS (pas juste fermer la fenêtre)
2. Vérifiez l'emplacement du fichier de config :
   • 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. Validez le JSON — collez la config dans https://jsonlint.com
4. Consultez les logs client pour les erreurs MCP :
   • Claude Desktop : ~/Library/Logs/Claude/mcp.log (macOS)
   • Cursor : View → Output → MCP
5. Exécutez le serveur MCP manuellement pour voir les erreurs de démarrage :

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

Problème : erreur « Mind Key invalid »

Symptômes

• Les outils apparaissent mais les appels échouent avec « 401 Unauthorized »
• Erreur : "Mind Key fehlt oder ungültig"

Solutions

1. Vérifiez le format de la Mind Key — commence par mk_, ~40 caractères
2. Testez directement :

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

3. Vérifiez que la variable d'env est définie — pour le transport stdio, la variable d'env doit être dans la config du serveur MCP, pas dans votre shell
4. Obtenez une nouvelle Mind Key :

   # Se connecter pour obtenir un JWT
   curl -X POST .../login -d '{"email":"...","password":"..."}'
   # Créer un nouveau mind
   curl -X POST .../minds -H "Authorization: Bearer YOUR_JWT" -d '{"name":"new mind"}'

Problème : npx introuvable

Symptômes

• Erreur : "npx: command not found"
• Le serveur MCP ne démarre pas

Solutions

1. Installez Node.js 18+ :
   • macOS : brew install node ou téléchargez depuis https://nodejs.org
   • Linux : curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - && sudo apt install -y nodejs
   • Windows : téléchargez depuis https://nodejs.org
2. Redémarrez le terminal après l'installation
3. Vérifiez : node --version && npx --version

Problème : SYNAPSE_URL inaccessible

Symptômes

• Le serveur MCP démarre mais les appels d'outils expirent
• Erreur : "fetch failed" ou "ECONNREFUSED"

Solutions

1. Testez la connectivité :

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

2. Vérifiez le pare-feu d'entreprise — peut bloquer le HTTPS sortant
3. Essayez une URL alternative :
   • Production : https://synapse.schaefer.zone
   • Serveur MCP : https://synapse-mcp.schaefer.zone
4. Pour l'auto-hébergement : assurez-vous que votre instance Synapse fonctionne et est accessible

Problème : le serveur MCP plante

Symptômes

• Le serveur MCP se ferme immédiatement après le démarrage
• Les logs client affichent « MCP server disconnected »

Solutions

1. Exécutez manuellement pour voir l'erreur :

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

2. Vérifiez les conflits de port — le serveur MCP utilise le port 13100 par défaut
3. Nettoyez le cache npx :

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

4. Mettez à jour vers la dernière version :

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

Problème : les appels d'outils renvoient 429

Symptômes

• Erreur : "Rate limit exceeded"

Solutions

Cela ne devrait pas arriver avec MCP (utilise l'auth par en-tête, sans limite de débit). Si c'est le cas :

1. Vérifiez si vous utilisez ?key= quelque part — passez à l'auth par en-tête
2. Vérifiez SYNAPSE_URL — assurez-vous qu'elle pointe vers la bonne instance
3. Contactez le support si le problème persiste

Problème : les outils apparaissent mais ne fonctionnent pas

Symptômes

• Outils listés dans le client
• Appeler un outil renvoie une erreur ou aucun résultat

Solutions

1. Vérifiez le nom de l'outil — doit être exact (ex. memory_recall, pas memory.recall)
2. Vérifiez les arguments — consultez le schéma d'entrée de l'outil
3. Testez via API directe :

   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. Vérifiez la santé de Synapse :

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

Obtenir de l'aide

Si aucune des solutions ci-dessus ne résout votre problème :

1. Consultez les tickets existants : https://gitlab.com/schaefer-services/synapse-mcp/-/issues
2. Ouvrez un nouveau ticket avec :
   • Version du serveur MCP (npx -y synapse-mcp-api@latest --version)
   • Nom et version du client
   • Système d'exploitation
   • Extraits de logs pertinents
   • Étapes pour reproduire

Prochaines étapes

• Configuration Claude Desktop
• Configuration Claude Code
• Erreurs API