{"title":"Dépannage MCP","slug":"troubleshooting","category":"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.","audience":["human","llm"],"tags":["mcp","troubleshooting","errors","debugging"],"difficulty":"intermediate","updated":"2026-06-27","word_count":694,"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":"fr","translated":true,"requested_lang":"fr","content_markdown":"\n# Dépannage MCP\n\nProblèmes courants et solutions lors de l'intégration de MCP Synapse avec votre client\nLLM.\n\n## Liste de vérification de diagnostic rapide\n\n1. ✅ Node.js 18+ installé ? (`node --version`)\n2. ✅ La Mind Key commence par `mk_` ? (pas un JWT `eyJ...`)\n3. ✅ L'API Synapse est accessible ? (`curl https://synapse.schaefer.zone/health`)\n4. ✅ La Mind Key fonctionne ? (`curl -H \"Authorization: Bearer mk_...\" .../memory/recall`)\n5. ✅ Le fichier de config est du JSON valide ? (pas de virgules finales, pas de commentaires)\n6. ✅ Le client a-t-il été redémarré après le changement de config ?\n7. ✅ Le serveur MCP démarre-t-il manuellement ? (`npx -y synapse-mcp-api@latest`)\n\n## Problème : aucun outil n'apparaît dans le client\n\n### Symptômes\n\n- Claude Desktop / Cursor / Continue affiche 0 outils\n- Pas d'icône 🔌 ou d'entrée « synapse » dans la liste des serveurs MCP\n\n### Solutions\n\n1. **Redémarrez le client complètement** — Cmd+Q sur macOS (pas juste fermer la fenêtre)\n2. **Vérifiez l'emplacement du fichier de config** :\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. **Validez le JSON** — collez la config dans \n4. **Consultez les logs client** pour les erreurs MCP :\n - Claude Desktop : `~/Library/Logs/Claude/mcp.log` (macOS)\n - Cursor : View → Output → MCP\n5. **Exécutez le serveur MCP manuellement** pour voir les erreurs de démarrage :\n ```bash\n SYNAPSE_MIND_KEY=mk_... npx -y synapse-mcp-api@latest\n ```\n\n## Problème : erreur « Mind Key invalid »\n\n### Symptômes\n\n- Les outils apparaissent mais les appels échouent avec « 401 Unauthorized »\n- Erreur : \"Mind Key fehlt oder ungültig\"\n\n### Solutions\n\n1. **Vérifiez le format de la Mind Key** — commence par `mk_`, ~40 caractères\n2. **Testez directement** :\n ```bash\n curl -H \"Authorization: Bearer mk_YOUR_KEY\" \\\n https://synapse.schaefer.zone/memory/recall\n ```\n3. **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\n4. **Obtenez une nouvelle Mind Key** :\n ```bash\n # Se connecter pour obtenir un JWT\n curl -X POST .../login -d '{\"email\":\"...\",\"password\":\"...\"}'\n # Créer un nouveau mind\n curl -X POST .../minds -H \"Authorization: Bearer YOUR_JWT\" -d '{\"name\":\"new mind\"}'\n ```\n\n## Problème : npx introuvable\n\n### Symptômes\n\n- Erreur : \"npx: command not found\"\n- Le serveur MCP ne démarre pas\n\n### Solutions\n\n1. **Installez Node.js 18+** :\n - macOS : `brew install node` ou téléchargez depuis \n - Linux : `curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - && sudo apt install -y nodejs`\n - Windows : téléchargez depuis \n2. **Redémarrez le terminal** après l'installation\n3. **Vérifiez** : `node --version && npx --version`\n\n## Problème : SYNAPSE_URL inaccessible\n\n### Symptômes\n\n- Le serveur MCP démarre mais les appels d'outils expirent\n- Erreur : \"fetch failed\" ou \"ECONNREFUSED\"\n\n### Solutions\n\n1. **Testez la connectivité** :\n ```bash\n curl https://synapse.schaefer.zone/health\n ```\n2. **Vérifiez le pare-feu d'entreprise** — peut bloquer le HTTPS sortant\n3. **Essayez une URL alternative** :\n - Production : `https://synapse.schaefer.zone`\n - Serveur MCP : `https://synapse-mcp.schaefer.zone`\n4. **Pour l'auto-hébergement** : assurez-vous que votre instance Synapse fonctionne et est accessible\n\n## Problème : le serveur MCP plante\n\n### Symptômes\n\n- Le serveur MCP se ferme immédiatement après le démarrage\n- Les logs client affichent « MCP server disconnected »\n\n### Solutions\n\n1. **Exécutez manuellement pour voir l'erreur** :\n ```bash\n SYNAPSE_MIND_KEY=mk_... SYNAPSE_URL=https://synapse.schaefer.zone \\\n npx -y synapse-mcp-api@latest\n ```\n2. **Vérifiez les conflits de port** — le serveur MCP utilise le port 13100 par défaut\n3. **Nettoyez le cache npx** :\n ```bash\n npx clear-npx-cache\n # ou\n rm -rf ~/.npm/_npx\n ```\n4. **Mettez à jour vers la dernière version** :\n ```bash\n npx -y synapse-mcp-api@latest --version\n ```\n\n## Problème : les appels d'outils renvoient 429\n\n### Symptômes\n\n- Erreur : \"Rate limit exceeded\"\n\n### Solutions\n\nCela ne devrait pas arriver avec MCP (utilise l'auth par en-tête, sans limite de\ndébit). Si c'est le cas :\n\n1. **Vérifiez si vous utilisez `?key=` quelque part** — passez à l'auth par en-tête\n2. **Vérifiez `SYNAPSE_URL`** — assurez-vous qu'elle pointe vers la bonne instance\n3. **Contactez le support** si le problème persiste\n\n## Problème : les outils apparaissent mais ne fonctionnent pas\n\n### Symptômes\n\n- Outils listés dans le client\n- Appeler un outil renvoie une erreur ou aucun résultat\n\n### Solutions\n\n1. **Vérifiez le nom de l'outil** — doit être exact (ex. `memory_recall`, pas `memory.recall`)\n2. **Vérifiez les arguments** — consultez le schéma d'entrée de l'outil\n3. **Testez via API directe** :\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. **Vérifiez la santé de Synapse** :\n ```bash\n curl https://synapse.schaefer.zone/health\n ```\n\n## Obtenir de l'aide\n\nSi aucune des solutions ci-dessus ne résout votre problème :\n\n1. **Consultez les tickets existants** : \n2. **Ouvrez un nouveau ticket** avec :\n - Version du serveur MCP (`npx -y synapse-mcp-api@latest --version`)\n - Nom et version du client\n - Système d'exploitation\n - Extraits de logs pertinents\n - Étapes pour reproduire\n\n## Prochaines étapes\n\n- [Configuration Claude Desktop](/docs/mcp/claude-desktop)\n- [Configuration Claude Code](/docs/mcp/claude-code)\n- [Erreurs API](/docs/api/errors)\n","content_html":"

Dépannage MCP

\n

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

\n

Liste de vérification de diagnostic rapide

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

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

\n

Symptômes

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

Solutions

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

Problème : erreur « Mind Key invalid »

\n

Symptômes

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

Solutions

\n
    \n
  1. Vérifiez le format de la Mind Key — commence par mk_, ~40 caractères
    2. \n
  2. Testez directement :
    curl -H "Authorization: Bearer mk_YOUR_KEY" \\\n     https://synapse.schaefer.zone/memory/recall
    3. \n
  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. \n
  4. Obtenez une nouvelle Mind Key :
    # Se connecter pour obtenir un JWT\ncurl -X POST .../login -d '{"email":"...","password":"..."}'\n# Créer un nouveau mind\ncurl -X POST .../minds -H "Authorization: Bearer YOUR_JWT" -d '{"name":"new mind"}'
    5. \n
\n

Problème : npx introuvable

\n

Symptômes

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

Solutions

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

Problème : SYNAPSE_URL inaccessible

\n

Symptômes

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

Solutions

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

Problème : le serveur MCP plante

\n

Symptômes

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

Solutions

\n
    \n
  1. Exécutez manuellement pour voir l'erreur :
    SYNAPSE_MIND_KEY=mk_... SYNAPSE_URL=https://synapse.schaefer.zone \\\n  npx -y synapse-mcp-api@latest
    2. \n
  2. Vérifiez les conflits de port — le serveur MCP utilise le port 13100 par défaut
    3. \n
  3. Nettoyez le cache npx :
    npx clear-npx-cache\n# ou\nrm -rf ~/.npm/_npx
    4. \n
  4. Mettez à jour vers la dernière version :
    npx -y synapse-mcp-api@latest --version
    5. \n
\n

Problème : les appels d'outils renvoient 429

\n

Symptômes

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

Solutions

\n

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

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

Problème : les outils apparaissent mais ne fonctionnent pas

\n

Symptômes

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

Solutions

\n
    \n
  1. Vérifiez le nom de l'outil — doit être exact (ex. memory_recall, pas memory.recall)
    2. \n
  2. Vérifiez les arguments — consultez le schéma d'entrée de l'outil
    3. \n
  3. Testez via API directe :
    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. Vérifiez la santé de Synapse :
    curl https://synapse.schaefer.zone/health
    5. \n
\n

Obtenir de l'aide

\n

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

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

Prochaines étapes

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