# Dépannage MCP
SUMMARY: Résolvez les problèmes courants d'intégration MCP — serveur qui ne démarre pas, outils qui n'apparaissent pas, erreurs d'auth.

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/

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é ? ()
2. ✅ La Mind Key commence par  ? (pas un JWT )
3. ✅ L'API Synapse est accessible ? ()
4. ✅ La Mind Key fonctionne ? ()
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 ? ()
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 : 
   - Claude Desktop Windows : 
   - Cursor : 
   - Continue : 
3. Validez le JSON — collez la config dans <https://jsonlint.com>
4. Consultez les logs client pour les erreurs MCP :
   - Claude Desktop :  (macOS)
   - Cursor : View → Output → MCP
5. Exécutez le serveur MCP manuellement pour voir les erreurs de démarrage :
   [CODE BLOCK]
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 , 40 caractères
2. Testez directement :
   [CODE BLOCK]
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 :
   [CODE BLOCK]
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 :  ou téléchargez depuis <https://nodejs.org>
   - Linux : 
   - Windows : téléchargez depuis <https://nodejs.org>
2. Redémarrez le terminal après l'installation
3. Vérifiez : 
Problème : SYNAPSEURL inaccessible
Symptômes
- Le serveur MCP démarre mais les appels d'outils expirent
- Erreur : "fetch failed" ou "ECONNREFUSED"
Solutions
1. Testez la connectivité :
   [CODE BLOCK]
2. Vérifiez le pare-feu d'entreprise — peut bloquer le HTTPS sortant
3. Essayez une URL alternative :
   - Production : 
   - Serveur MCP : 
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 :
   [CODE BLOCK]
2. Vérifiez les conflits de port — le serveur MCP utilise le port 13100 par défaut
3. Nettoyez le cache npx :
   [CODE BLOCK]
4. Mettez à jour vers la dernière version :
   [CODE BLOCK]
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  quelque part — passez à l'auth par en-tête
2. Vérifiez  — 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. , pas )
2. Vérifiez les arguments — consultez le schéma d'entrée de l'outil
3. Testez via API directe :
   [CODE BLOCK]
4. Vérifiez la santé de Synapse :
   [CODE BLOCK]
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 ()
   - 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