Sommaire
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 approvalMCP donne à Claude Code des « mains » — des outils externes (opérations sur fichiers, GitHub, bases de données, diverses API) — mais ses connexions échouent plus souvent qu'on ne le croit. Les causes se répartissent en trois familles : « échec de lancement d'un sous-processus local », « authentification distante » et « erreurs dans le fichier de configuration », et le statut /mcp vous indique laquelle. Cet article expose comment lire le statut, les correctifs cause par cause, le principal piège sous Windows et le workflow de diagnostic — sur la base d'informations officielles.
Les points clés d'abord. (1) Regardez d'abord le statut avec /mcp (et claude mcp list) — failed (échec de lancement), needs authentication (authentification) et pending approval (en attente d'approbation) demandent chacun des correctifs complètement différents. (2) En local (stdio), les coupables habituels sont les chemins et les variables d'environnement, plus le problème npx sous Windows. (3) En distant (HTTP), le coupable habituel est OAuth. (4) En cas de blocage, lancez claude --debug mcp pour voir la sortie d'erreur du serveur (stderr). Les comportements et les valeurs par défaut changent selon la version, alors vérifiez par rapport à la dernière documentation officielle.
Le statut vous indique le correctif
— failed / needs auth / pending ont chacun un remède différent
✗ failed = un problème de lancement local, △ needs auth = authentification distante, ⏸ pending = en attente d'approbation.
Ne mettez pas tous les « ça ne se connecte pas » dans le même sac — classez d'abord par statut ; c'est la voie la plus courte.
1. Ce que cette erreur vous indique
Les serveurs MCP existent selon deux grands types de connexion. (1) stdio (local) — Claude Code lance la commande du serveur comme sous-processus sur votre machine et communique via les entrées/sorties standard. (2) HTTP (distant) — il se connecte à un serveur cloud par URL (l'ancien SSE est déprécié). Ce que « ça ne se connecte pas » signifie dépend fortement du type.
Un échec local (stdio) est presque toujours « la commande elle-même n'a pas réussi à se lancer » — mauvais chemin, npx qui ne se résout pas (surtout sous Windows), ou le serveur qui plante immédiatement parce qu'une variable d'environnement requise manque. Un échec distant (HTTP) est généralement « OAuth n'a pas été complété » — le serveur renvoie 401/403 et affiche needs authentication. Et quand ce n'est ni l'un ni l'autre, mais que la configuration reste sans effet, soupçonnez l'emplacement du fichier de configuration, une coquille dans le JSON, ou l'approbation du projet.
Le premier réflexe est donc d'« ouvrir /mcp, lire le statut et identifier laquelle des trois familles est en cause ». Traiter chaque erreur comme un « ça ne se connecte pas » générique et tâtonner au hasard est le chemin le plus long. La section suivante explique comment lire le statut.
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 :
| Statut | Signification | Où regarder en premier |
|---|---|---|
| ✓ connected | Connecté. Le nombre d'outils s'affiche à côté | Si le nombre d'outils est 0 : « connecté mais aucun outil » → reconnecter / déboguer |
| ✗ failed | Échec de lancement, ou tentatives épuisées | Lancement local = commande, chemin, npx, variables d'environnement (§3, §4) |
| △ needs authentication | Le distant a renvoyé 401/403. OAuth non effectué | Lancer l'authentification depuis /mcp (approuver dans le navigateur) |
| ⏸ pending approval | En attente d'approbation d'un serveur de projet .mcp.json | Approuver dans /mcp. Si refusé par erreur : claude mcp reset-project-choices |
| ✗ rejected | Un serveur de projet que vous avez précédemment refusé | Idem (reset-project-choices pour réapprouver) |
L'essentiel : « failed = un problème de lancement, needs authentication = authentification, pending = approbation » — le statut détermine de façon univoque votre action. Un cas souvent négligé est « connecté mais 0 outil » — le serveur a démarré mais ne renvoie pas de liste d'outils ; passez à une reconnexion ou vérifiez les logs avec claude --debug mcp.
3. Principales causes d'échec et correctifs
Voici les causes représentatives de failed (échec de lancement local) et de problèmes de configuration, associées à leurs correctifs.
Principaux moteurs des problèmes failed / config
spawn ... ENOENT.env propre au serveur (dans .mcp.json ou --env). L'env de settings.json N'ATTEINT PAS MCP.MCP_TIMEOUT (ms) au lancement, p. ex. MCP_TIMEOUT=10000 claude..mcp.json de projet va à la racine du dépôt (pas sous .claude/, ni dans settings.json). Une ${VAR} non définie fait échouer l'analyse de la config.needs authentication. OAuth depuis /mcp. À noter : un en-tête d'authentification statique rejeté est signalé comme failed.
Pour le local, vérifiez dans l'ordre : 1) chemin → 2) variables d'env → 4) emplacement de config.
Pour le distant, l'6) authentification est presque tout. Le piège Windows de la section suivante est aussi très courant.
Un .mcp.json de projet peut être partagé via git et demande une approbation la première fois. Si vous écartez cette invite par accident, le serveur reste désactivé (pending/rejected). Lancez claude mcp reset-project-choices pour refaire l'approbation. Associez ceci aux bases de MCP et à la communication inter-agents A2A pour avoir une vue d'ensemble de la connectivité.
4. Quand ça échoue sous Windows (le piège n°1)
Sous Windows natif, les serveurs MCP basés sur npx qui ne se connectent pas avec spawn npx ENOENT / Failed to connect sont extrêmement courants. La cause : sous Windows, npx est en réalité un shim batch (npx.cmd), et le spawn de processus de Node ne peut pas résoudre directement un .cmd.
Correctif : encapsulez-le dans cmd /c
Faites en sorte que command soit cmd au lieu de npx directement, et passez /c npx ... en arguments :
{
"command": "cmd",
"args": ["/c", "npx", "-y", "@scope/your-mcp-server"]
}Ou exécutez-le sous WSL, ce qui est fiable. Si where npx affiche un chemin mais que ça échoue quand même, soupçonnez d'abord ce problème de .cmd. Certaines occurrences propres à une version peuvent être corrigées dans des versions ultérieures, alors essayez aussi de mettre à jour vers la dernière version.
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.
Isolez le problème du haut vers le bas
/mcp et claude mcp list / get pour vérifier le statut (failed vs auth vs pending).claude --debug mcp pour lire le stderr (sortie d'erreur) du serveur. La raison du plantage est généralement juste là.npx ... s'exécute dans le même shell ?). Sinon, c'est un problème en amont de Claude Code.npx @modelcontextprotocol/inspector) — inspectez sa liste d'outils et invoquez les outils dans une interface.mcp*.log. /doctor permet aussi de vérifier.
La règle : confirmez d'abord « est-ce que le serveur s'exécute de façon autonome ? ».
Une fois cela réglé, le reste se réduit à la config (chemin, env, emplacement) ou à l'authentification.
À noter : ajouter trop de serveurs MCP fait que les définitions d'outils dévorent le contexte (surtout avec les configurations à chargement permanent). Claude Code diffère les définitions d'outils via la recherche d'outils par défaut, donc l'impact est faible, mais il reste judicieux de désactiver les serveurs que vous n'utilisez pas. Surcharger le contexte peut même déclencher Prompt is too long.
6. Liste de prévention
Des habitudes pour ne plus se retrouver bloqué sur les connexions MCP.
(1) Spécifiez les scripts locaux avec des chemins absolus. (2) Mettez les clés du serveur dans l'env propre au serveur (pas dans settings.json). (3) Sous Windows, encapsulez avec cmd /c npx ... (ou utilisez WSL). (4) Gardez .mcp.json à la racine du dépôt ; surveillez la syntaxe JSON et les ${VAR} non définies. (5) Les serveurs ne doivent pas écrire de logs sur stdout (utilisez stderr). (6) Après une modification de config, rechargez (redémarrez complètement Desktop ; réapprouvez les serveurs de projet). (7) En cas de blocage, isolez avec claude --debug mcp et un lancement autonome du serveur, et mettez à jour vers la dernière version si nécessaire.
En résumé
Pour les erreurs de connexion des serveurs MCP de Claude Code, la voie la plus courte est de classer par le statut /mcp en trois familles. ✗ failed est un problème de lancement local (chemin, variables d'env, délai, emplacement de config — et sous Windows, encapsulez npx avec cmd /c), △ needs authentication est l'OAuth distant (authentifiez-vous depuis /mcp), et ⏸ pending approval est un serveur de projet en attente d'approbation (approuvez dans /mcp ; un refus erroné se corrige avec claude mcp reset-project-choices).
Diagnostiquez dans l'ordre : (1) statut avec /mcp -> (2) stderr avec claude --debug mcp -> (3) lancement autonome -> (4) MCP Inspector -> (5) redémarrage complet de Desktop. Confirmez que le serveur s'exécute de façon autonome avant d'accuser Claude Code, et le reste se réduit à la config ou à l'authentification. Trois habitudes suffisent — variables d'env dans l'env propre au serveur, .mcp.json à la racine du dépôt, logs vers stderr — pour réduire drastiquement les incidents. À lire aussi : Qu'est-ce que MCP, Monétiser les serveurs MCP, Panorama des erreurs Claude Code.
FAQ
Q. /mcp affiche « failed ». Par où commencer ?
A. failed est le plus souvent un échec de lancement d'un serveur local (stdio). Vérifiez dans l'ordre : (1) le chemin de la commande/du script (utilisez des chemins absolus), (2) les variables d'environnement requises (mettez-les dans l'env propre au serveur), et (3) sous Windows, encapsulez avec cmd /c npx .... Si la cause reste obscure, lisez le stderr du serveur avec claude --debug mcp, et testez d'abord si le serveur se lance de façon autonome dans le même shell.
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. Sous Windows, mon serveur npx ne veut tout simplement pas se connecter.
A. Sous Windows, npx est en réalité un shim batch (npx.cmd), qui échoue souvent au lancement avec spawn npx ENOENT. Changez command en cmd et args en ["/c","npx","-y","nom-du-paquet"] pour l'encapsuler. L'exécuter sous WSL est également fiable. Si where npx affiche un chemin mais que ça échoue quand même, c'est presque certainement ce problème de .cmd. Il se peut que ce soit corrigé dans des versions plus récentes, alors essayez aussi de mettre à jour.
Q. Il est « connected » mais affiche 0 outil.
A. Le serveur s'est lancé avec succès mais ne renvoie pas de liste d'outils. Une cause courante est un serveur stdio qui écrit des logs sur stdout et corrompt le protocole — envoyez toujours les logs vers stderr. Reconnectez d'abord depuis /mcp ; si cela ne corrige pas, vérifiez la sortie du serveur avec claude --debug mcp.
Q. J'ai configuré un serveur mais il n'apparaît pas dans /mcp.
A. L'emplacement du fichier de configuration est la cause probable. Un serveur de projet partagé va dans .mcp.json à la racine du dépôt (il n'est pas lu sous .claude/ ni dans settings.json). Une ${VAR} non définie fait aussi échouer l'analyse de la config. Les serveurs de projet nécessitent une approbation initiale ; si vous écartez l'invite, il reste pending — refaites-la avec claude mcp reset-project-choices.
