Erreur de connexion d'un serveur MCP dans Claude Code : causes et correctifs

Vous avez configuré un serveur MCP (Model Context Protocol), mais en ouvrant /mcp il reste bloqué dans un état comme celui-ci — ça vous parle ?

/mcp

  filesystem      ✓ connected      (12 tools)
  github          ✗ failed
  notion          △ needs authentication
  my-server       ⏸ pending approval

MCP permet à Claude Code de travailler avec des outils et des données externes. Si la connexion échoue, ne posez pas un diagnostic sur le seul statut : examinez aussi le mode de connexion et les détails de l’erreur. Cet article traite du démarrage local, des communications et de l’authentification à distance, de la configuration et de l’approbation.

L’essentiel : (1) lisez le statut et les détails avec /mcp et claude mcp get <name>. (2) failed peut concerner un serveur local comme distant. Pour stdio, vérifiez la commande et les variables d’environnement ; pour HTTP, l’URL, le réseau, la réponse du serveur et l’authentification. (3) Si la cause reste floue, consultez les journaux de connexion avec claude --debug=mcp. Ne modifiez que ce qu’indique l’erreur réelle, puis reconnectez-vous pour vérifier le résultat.

1. Ce que cette erreur vous indique

Vous pouvez, par exemple, rencontrer cette erreur dans un journal. Ce message seul ne prouve pas que le serveur n’a pas démarré ; consultez aussi les entrées précédentes.

MCP error -32000: Connection closed

MCP error -32000: Connection closed indique que la connexion s’est fermée. Le SDK TypeScript de MCP associe -32000 à ConnectionClosed. Consultez les journaux précédents pour déterminer ce qui l’a fermée, par exemple l’arrêt du serveur ou une perte de connexion. Le message ne permet pas de savoir si le processus s’est arrêté avant l’initialisation ou si la connexion a été coupée ensuite. Voir la gestion de la fermeture des connexions dans le SDK.

Des bugs indépendants de votre configuration sont aussi possibles. Ainsi, l’issue #20713 contient le signalement d’un utilisateur concernant une déconnexion à l’initialisation avec Claude Code 2.1.19 sur macOS. Ne présentez pas le diagnostic d’un utilisateur comme une cause confirmée par Anthropic ou comme un bug actuel touchant tous les environnements. Dans un signalement, indiquez le système, la version, le mode de connexion et les journaux débarrassés des secrets.

Les serveurs MCP utilisent couramment deux types de connexion. (1) stdio (local) : Claude Code lance la commande du serveur comme sous-processus sur votre machine et communique par les entrées-sorties standard. (2) HTTP (distant) : il se connecte à un serveur dans le cloud par son URL (l’ancien SSE est obsolète). Le sens de « ne se connecte pas » dépend beaucoup du type.

Pour un serveur local (stdio), recherchez une commande ou des variables manquantes, un arrêt du serveur ou des journaux mêlés à stdout. Pour un serveur distant (HTTP), vérifiez l’URL, les problèmes réseau, les réponses 5xx, les délais d’attente et l’authentification. L’emplacement, la syntaxe et la portée de la configuration comptent dans les deux cas. N’affirmez pas que les pannes viennent « presque toujours de l’authentification » ou « presque toujours des chemins » sans données sur leur fréquence.

D’abord, notez le statut et les détails de l’erreur, puis déterminez si la connexion utilise stdio ou HTTP. Modifier plusieurs réglages à la fois empêche de savoir lequel a aidé. Utilisez le tableau suivant comme point de départ, puis examinez une cause pertinente à la fois.

2. Lisez d'abord le statut avec /mcp

Lancez /mcp en session (ou claude mcp list / claude mcp get <name> depuis le shell) pour voir l'état de chaque serveur. Les principaux statuts et leurs significations :

failed seul ne distingue pas un problème de démarrage local d’un échec de communication à distance. Lisez le code HTTP ou le corps de l’erreur dans Issue: avec claude mcp get <name>, ou dans les détails de /mcp. Un en-tête fixe Authorization rejeté avec 401/403 pendant la connexion produit aussi failed. De plus, zéro outil n’est pas forcément une erreur si le serveur ne fournit que des ressources ou des prompts. Vérifiez d’abord s’il est censé proposer des outils. Voir les détails officiels des statuts du serveur.

3. Principales causes d'échec et correctifs

Ces vérifications aident à rechercher les échecs de connexion et les incohérences de configuration. Commencez par celles qui correspondent à votre mode de connexion.

Vous pouvez partager le .mcp.json du projet, mais ne commitez pas directement de valeurs secrètes. Référencez par exemple ${API_KEY} et définissez sa valeur dans chaque environnement. Certains noms de variables protégés, dont les identifiants de Claude Code lui-même, sont remplacés par des chaînes vides dans les URL et en-têtes distants ; consultez les règles officielles d’expansion. Les sessions interactives demandent une approbation pour les serveurs du projet. À l’inverse, claude -p et le SDK les chargent normalement sans cette question. Consultez la documentation officielle de la portée projet pour les réglages de rejet et les autres conditions. Voir aussi les bases de MCP et A2A.

4. Vérifier le lancement de npx sous Windows

Si Windows affiche spawn npx ENOENT, vérifiez d’abord l’exécutable et PATH avec where.exe npx. Vérifiez aussi si Node/npm fonctionne et si le paquet indiqué peut démarrer. La documentation officielle de Node explique que les fichiers .cmd ne peuvent pas être exécutés directement et montre comment les lancer via un shell ou cmd.exe. Cependant, cela ne signifie pas que spécifier directement npx échoue dans tous les environnements Claude Code.

{
  "command": "cmd.exe",
  "args": ["/c", "npx", "-y", "@scope/your-mcp-server"]
}

5. Le workflow de diagnostic

Quand la cause n'est pas claire, procédez du haut vers le bas. L'astuce est de confirmer que le serveur s'exécute de façon autonome avant d'accuser Claude Code.

Remarque : ajouter trop de serveurs MCP fait que les définitions d’outils consomment du contexte (surtout lorsqu’elles sont toujours chargées). Claude Code diffère ces définitions grâce à la recherche d’outils par défaut, ce qui réduit l’impact ; il reste néanmoins judicieux de désactiver les serveurs inutilisés. Surcharger le contexte peut même provoquer Prompt is too long.

6. Liste de prévention

Des habitudes pour ne plus se retrouver bloqué sur les connexions MCP.

(1) Vérifiez les chemins réels des exécutables et scripts stdio. (2) Distinguez les variables stdio des en-têtes d’authentification HTTP et gardez les secrets hors des fichiers partagés. (3) Sous Windows, vérifiez where.exe npx et Node/npm ; essayez cmd.exe /c uniquement si le mode de lancement est en cause. (4) Placez .mcp.json à la racine du projet et vérifiez la syntaxe JSON, les variables et l’approbation. (5) Envoyez les journaux stdio vers stderr, pas stdout. (6) Modifiez un seul élément à la fois, puis reconnectez-vous et testez l’opération nécessaire.

En résumé

Recherchez la cause des erreurs de connexion MCP de Claude Code en combinant statut, mode de connexion et détails de l’erreur. failed ne se limite pas aux échecs de démarrage local : des problèmes de communication HTTP et des en-têtes fixes d’authentification rejetés peuvent aussi le produire. needs authentication oriente vers les vérifications d’authentification, et pending approval vers l’approbation d’un serveur du projet.

Procédez ainsi : lisez le statut et Issue: → consultez les journaux adaptés au mode de connexion → testez le fonctionnement indépendant ou la communication → reconnectez-vous et vérifiez l’opération. Sélectionnez la catégorie de débogage avec claude --debug=mcp. Ajoutez --debug-file ./claude-mcp-debug.log pour enregistrer les journaux. Retirez les secrets avant de les partager. À lire aussi : Qu’est-ce que MCP, Monétiser des serveurs MCP, Erreurs courantes de Claude Code.

FAQ

Q. /mcp affiche failed. Par où commencer ?
R. Vérifiez le mode de connexion et Issue:. Pour stdio, examinez la commande, le chemin, les variables d’environnement et stderr ; pour HTTP, l’URL, le réseau, la réponse du serveur et l’authentification. Un en-tête fixe Authorization rejeté avec 401/403 pendant la connexion produit aussi failed : ne concluez pas à un problème de démarrage local.

Q. Il indique « needs authentication » et les outils ne fonctionnent pas.
A. C'est un serveur distant (HTTP) qui demande une authentification (401/403). Ouvrez /mcp et lancez l'authentification pour ce serveur ; cela passe à l'approbation OAuth dans le navigateur. Une fois fait, les jetons sont stockés en toute sécurité et rafraîchis automatiquement. Notez que certains services (Microsoft 365, Gmail, Google Calendar) ne prennent pas en charge l'authentification locale depuis Claude Code et doivent être connectés via Settings → Connectors sur claude.ai à la place.

Q. Mon serveur npx ne se connecte pas sous Windows.
R. Vérifiez where.exe npx et Node/npm, puis essayez de lancer le même paquet avec les mêmes arguments. Si le problème vient de la manière de lancer le fichier .cmd, vous pouvez utiliser cmd.exe /c npx .... WSL exige aussi un environnement Linux fonctionnel. Changer de système d’exploitation ne garantit pas une solution.

Q. Le serveur est connected, mais affiche 0 outil.
R. Vérifiez s’il est conçu pour fournir des outils. Zéro outil n’est pas forcément une erreur s’il ne fournit que des ressources ou des prompts. Si des outils devraient être disponibles, examinez les capacités exposées, les autorisations, les réglages du serveur et les journaux, puis reconnectez-vous. Envoyez les journaux de diagnostic stdio vers stderr, pas vers le flux stdout utilisé par le protocole.

Q. J’ai configuré un serveur, mais je ne peux pas l’utiliser.
R. Vérifiez que le .mcp.json partagé se trouve à la racine du projet, puis contrôlez la syntaxe, la portée et l’approbation. Une ${VAR} non définie et sans valeur par défaut déclenche un avertissement et reste sous forme de texte littéral au chargement de la configuration, ce qui peut provoquer un échec de démarrage ou d’authentification. Indiquez aussi type dans les configurations HTTP. Répéter l’approbation ne résout pas à lui seul les réglages de rejet ni les politiques gérées.

Références de configuration et de commandes : réglages env, référence CLI, référence des connexions MCP.