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. Quand la connexion échoue, le journal peut aussi afficher la ligne MCP error -32000: Connection closed. En combinant trois éléments, le statut, le mode de connexion et les détails de l’erreur, vous pouvez cerner la cause. Cet article examine dans l’ordre le démarrage local, les communications et l’authentification à distance, puis la configuration et l’approbation.

L’essentiel : (1) lisez le statut et les détails avec /mcp et claude mcp get <name>. (2) failed apparaît pour un serveur local comme distant. Pour stdio, examinez 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, récupérez les journaux de connexion avec claude --debug=mcp. Ne corrigez que ce qui correspond à l’erreur réelle, puis reconnectez-vous pour vérifier le résultat.

1. Ce que cette erreur vous indique

Quand la connexion se ferme, le journal affiche la ligne suivante.

MCP error -32000: Connection closed

MCP error -32000: Connection closed indique que la connexion MCP s’est fermée. Le SDK TypeScript de MCP associe -32000 à ConnectionClosed et affiche ce message quand la connexion se ferme (voir la gestion de la fermeture des connexions dans le SDK). Cette ligne n’indique que le résultat, « fermée » : la raison de la fermeture se trouve dans les entrées de journal qui la précèdent. C’est là que vous distinguerez un processus serveur arrêté avant l’initialisation d’une communication coupée après la connexion.

La connexion peut se fermer même avec une configuration correcte. L’issue #20713 est le signalement d’un utilisateur dont la connexion s’est fermée pendant l’initialisation, avec Claude Code 2.1.19 sur macOS. La cause avancée, une « condition de concurrence », relève de l’analyse de l’auteur, et cette issue a été fermée en avril 2026 avec le statut not planned. Si vous faites vous-même 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), les échecs typiques sont une commande introuvable, des variables manquantes, un serveur qui s’arrête aussitôt ou des journaux mêlés à stdout. Pour un serveur distant (HTTP), les causes sont une URL erronée, le réseau, les réponses 5xx, les délais d’attente et l’authentification. Les erreurs d’emplacement, de syntaxe et de portée du fichier de configuration surviennent avec les deux types.

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 apparaît aussi bien pour un échec de démarrage local que pour un échec de communication à distance. Les détails permettent de les distinguer : le statut HTTP ou le code d’erreur, ainsi que le corps de l’erreur renvoyé par le serveur, s’affichent en fin de ligne ✘ Failed to connect dans claude mcp list, et sur la ligne Issue: dans claude mcp get <name> et l’écran de détails de /mcp. Un en-tête fixe Authorization rejeté avec 401/403 pendant la connexion produit lui aussi failed.

Si un serveur distant se déconnecte en cours de session, Claude Code tente automatiquement de se reconnecter, et /mcp affiche pending pendant ce temps (un sens différent de l’attente d’approbation). Si les cinq tentatives échouent et que le serveur passe à failed, la notification MCP server "<name>" disconnected · open /mcp to reconnect apparaît (s’il faut s’authentifier de nouveau, il passe à needs authentication). Les serveurs stdio ne se reconnectent pas automatiquement : reconnectez-les manuellement depuis /mcp. Par ailleurs, /mcp signale les serveurs qui déclarent la fonctionnalité d’outils sans exposer aucun outil. Un serveur qui ne fournit que des ressources ou des prompts fonctionne normalement avec zéro outil. 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 (règles officielles d’expansion). Les sessions interactives demandent une approbation pour les serveurs du projet, mais claude -p et le SDK les chargent sans poser cette question. Pour empêcher malgré tout le chargement d’un serveur, inscrivez-le dans disabledMcpjsonServers (documentation officielle de la portée projet). À lire aussi : bases de MCP, A2A.

4. Vérifier le lancement de npx sous Windows

Si Windows affiche spawn npx ENOENT, examinez d’abord l’exécutable et PATH avec where.exe npx. Essayez ensuite si Node/npm fonctionne et si le paquet indiqué démarre seul. Selon la documentation officielle de Node, les fichiers .cmd de Windows ne peuvent pas s’exécuter seuls : il faut les lancer via un shell ou cmd.exe.

{
  "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 de soupçonner Claude Code.

Remarque : par défaut, Claude Code charge les définitions à la demande grâce à la recherche d’outils ; ajouter des serveurs pèse donc peu sur le contexte. Mais avec un serveur configuré en alwaysLoad, ou si la recherche d’outils est désactivée, les définitions sont chargées dès le départ : par sécurité, désactivez les serveurs inutilisés avec /mcp disable <name>. Surcharger le contexte peut conduire à Prompt is too long.

6. Liste de prévention

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

(1) Indiquez 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 contrôlez 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: → lisez les journaux adaptés au mode de connexion → testez le fonctionnement indépendant ou la communication → reconnectez-vous et testez 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.

Dans l’application Codex, un historique visible alors que seul l’envoi échoue relève non pas de MCP, mais de l’état de la conversation. Ce cas est traité dans Codex « thread not found » : diagnostic et exemple de rétablissement.

FAQ

Q. /mcp affiche failed. Par où commencer ?
R. Examinez le mode de connexion et Issue:. Pour stdio, les pistes sont 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, et Issue: affiche alors le statut HTTP.

Q. Il indique « needs authentication » et les outils ne fonctionnent pas.
R. La marche à suivre dépend de la méthode d’authentification. Pour un serveur OAuth, authentifiez-vous dans /mcp. Avec un headersHelper personnalisé, cet état apparaît lorsqu’un appel d’outil renvoie 401/403 et que la nouvelle tentative avec des identifiants renouvelés échoue aussi. Si le helper fournit un en-tête Authorization, Claude Code ne passe pas à OAuth : corrigez la source et la valeur des identifiants, puis reconnectez-vous. Les connecteurs hébergés par Anthropic, comme Microsoft 365, Gmail et Google Calendar, ne prennent pas en charge OAuth en local depuis Claude Code. Si vous les ajoutez avec claude mcp add ou .mcp.json puis tentez de vous connecter depuis /mcp, le message is Anthropic-hosted and doesn't support local OAuth s’affiche : supprimez cet enregistrement et connectez-vous dans les paramètres des connecteurs de claude.ai. Consultez la documentation officielle sur l’authentification personnalisée.

Q. Mon serveur npx ne se connecte pas sous Windows.
R. Examinez 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, cmd.exe /c npx ... permet de le démarrer. Pour l’exécuter sous WSL, installez Node et les paquets côté Linux.

Q. Le serveur est connected, mais affiche 0 outil.
R. Regardez d’abord s’il est conçu pour fournir des outils. Un serveur qui ne fournit que des ressources ou des prompts fonctionne normalement avec zéro outil. S’il déclare la fonctionnalité d’outils mais n’en expose aucun, /mcp le signale : examinez alors 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 revoyez la syntaxe, la portée et l’approbation. Une ${VAR} non définie et sans valeur par défaut déclenche un avertissement, puis est chargée telle quelle sous forme de texte littéral, ce qui entraîne des échecs de démarrage ou d’authentification. Indiquez aussi type dans les configurations HTTP. Si claude mcp get <name> renvoie ✘ Rejected, le serveur figure dans disabledMcpjsonServers d’un des fichiers de réglages : au lieu de simplement refaire l’approbation, retirez cette entrée.

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