Config MCP de Claude Code : .mcp.json, portées et dépannage

2026-09-09 Mis à jour: 2026-09-14

Claude Code lit les serveurs MCP depuis deux fichiers : .mcp.json à la racine du projet pour les serveurs partagés avec l'équipe, et ~/.claude.json pour vos propres serveurs locaux et à portée utilisateur. Les deux utilisent le même objet mcpServers, où chaque entrée nomme un type valant http, sse, ws ou stdio, et un serveur qui n'apparaît pas est presque toujours dû à un mauvais type, une variable d'environnement non développée, ou une connexion qui n'a jamais abouti.

Le format de .mcp.json

Un fichier de projet avec un serveur distant et un serveur local ressemble à ceci :

{
  "mcpServers": {
    "hosttracker": {
      "type": "http",
      "url": "https://mcp.host-tracker.com/mcp"
    },
    "local-tool": {
      "type": "stdio",
      "command": "/path/to/executable",
      "args": ["--flag", "value"],
      "env": { "KEY": "value" },
      "timeout": 600000
    }
  }
}

Le champ type est requis dès que url est présent. Un url sans type est signalé comme une erreur de configuration (le message vous invite à ajouter "type": "http", ou sse ou ws), ce qui a remplacé une ancienne plainte bien moins utile à propos d'un command manquant. La valeur streamable-http est acceptée comme alias de http. Un serveur distant qui a besoin d'un identifiant fixe prend un objet headers ; un serveur local prend command, args et env. Le champ optionnel timeout est une limite par appel d'outil, en millisecondes. Les serveurs WebSocket ne peuvent être déclarés que dans un fichier ou via claude mcp add-json ; l'option --transport n'accepte pas ws.

La commande claude mcp add avec --scope project écrit ce fichier pour vous, donc l'édition manuelle n'est nécessaire que pour les champs que la commande n'expose pas, ou quand vous préférez relire le changement dans une pull request.

Garder les secrets hors du fichier

Comme .mcp.json est destiné à être committé, les jetons ne doivent pas y être écrits directement. Claude Code développe les variables d'environnement dans command, args, env, url et headers : ${VAR} prend la valeur de la variable, et ${VAR:-default} retombe sur la valeur par défaut quand elle n'est pas définie.

{
  "mcpServers": {
    "secure-api": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": { "Authorization": "Bearer ${API_KEY}" }
    }
  }
}

Une variable référencée qui n'est pas définie et n'a pas de valeur par défaut n'empêche pas le serveur de se charger ; le texte littéral ${API_KEY} est envoyé tel quel, et claude mcp list affiche un avertissement. Cet avertissement est la première chose à chercher quand un serveur se connecte mais que chaque appel est rejeté comme non autorisé.

Pour un serveur qui prend en charge OAuth, il n'y a rien du tout à cacher : laissez l'entrée avec seulement type et url, et chaque utilisateur se connecte une fois depuis /mcp. Le jeton est stocké par utilisateur, hors du dépôt, et supprimé à nouveau par claude mcp remove.

Approbation, priorité et serveurs gérés

La première fois que Claude Code voit un serveur dans le .mcp.json d'un projet, une session interactive demande s'il faut l'utiliser ; les exécutions non interactives (claude -p, le SDK d'agent, les sessions cloud) le chargent sans demander. La décision est mémorisée par projet ; claude mcp reset-project-choices l'oublie pour que vous puissiez réapprouver après un changement.

Quand un même nom est défini à plusieurs endroits, l'ordre est portée locale, puis portée projet, puis portée utilisateur, puis les serveurs fournis par les extensions, puis les connecteurs de claude.ai. C'est l'entrée gagnante entière qui est utilisée. Les organisations peuvent imposer une liste fixe de serveurs via un fichier de configuration géré ou le paramètre managedMcpServers (Claude Code 2.1.259 ou ultérieur) ; ceux-ci priment sur toute portée utilisateur, et un fichier géré qui revendique un contrôle exclusif fait échouer claude mcp add avec un message indiquant qu'une configuration d'entreprise est active. Des listes d'autorisation et de refus (allowedMcpServers, deniedMcpServers) peuvent aussi restreindre les URL ou commandes que les utilisateurs peuvent ajouter, et un refus l'emporte toujours.

Lire la sortie de statut

claude mcp list indique pour chaque serveur s'il est connecté, a besoin d'authentification, a échoué à se connecter, est en attente d'approbation, a été rejeté via disabledMcpjsonServers, ou est désactivé pour ce projet. Quelques avertissements moins évidents qu'elle affiche valent la peine d'être connus : des espaces cachés en début ou fin de valeur (un jeton collé qui se terminait par un retour à la ligne), le même nom pointant vers des points de terminaison différents dans deux portées, et une poignée de noms réservés qui ne peuvent pas être utilisés pour vos propres serveurs. Les serveurs WebSocket n'apparaissent pas du tout dans la liste ; vérifiez-les avec claude mcp get <name> ou /mcp.

Échecs courants et leurs corrections

Un serveur distant affiche « needs authentication » ou répond 401 ou 403. Ouvrez /mcp, sélectionnez le serveur et terminez la connexion dans le navigateur, ou exécutez claude mcp login <name>. Si le serveur utilise un jeton statique, vérifiez la valeur de l'en-tête et l'avertissement sur les variables non développées.
Un serveur local échoue à se connecter au démarrage. Exécutez sa commande à la main dans le même shell pour voir la vraie erreur ; les causes habituelles sont un environnement d'exécution manquant, un paquet à installer, ou une variable d'environnement requise. Les serveurs lents à démarrer atteignent la limite de démarrage, que MCP_TIMEOUT relève en millisecondes, par exemple MCP_TIMEOUT=10000 claude.
Le serveur se connecte mais un outil renvoie un résultat tronqué. La sortie d'outil est plafonnée à 25 000 jetons par défaut, avec un avertissement à partir de 10 000 ; MAX_MCP_OUTPUT_TOKENS relève ce plafond.
Les outils semblent manquer dans la conversation. Claude Code diffère les définitions d'outils jusqu'à ce qu'elles soient nécessaires pour garder un contexte réduit, donc seuls les noms et les instructions du serveur se chargent au démarrage ; l'assistant les retrouve quand même quand une demande correspond. Définissez "alwaysLoad": true sur une entrée de serveur si vous voulez que ses définitions complètes soient présentes dès le premier tour.
Un serveur distant se déconnecte en cours de session. Claude Code retente une connexion perdue jusqu'à cinq fois avec des délais croissants, et une première connexion HTTP échouée jusqu'à trois fois, mais pas pour les erreurs d'authentification ni pour les serveurs locaux, donc un échec d'authentification ne se corrigera pas de lui-même.

Tester la configuration contre un service en direct

Le moyen le plus rapide de valider le .mcp.json d'un projet est un serveur dont vous pouvez vérifier les réponses de manière indépendante. Avec { "type": "http", "url": "https://mcp.host-tracker.com/mcp" } committé et chaque développeur connecté une fois via /mcp, une demande comme « lance une vérification HTTP sur notre URL de préproduction depuis l'Europe et l'Asie » doit revenir avec de vrais codes de statut et des temps de réponse depuis les points de contrôle de HostTracker, ce qui prouve soit que le fichier est lu correctement, soit réduit la panne à un problème de connexion. Le guide complémentaire, comment ajouter un serveur MCP à Claude Code, couvre la voie en ligne de commande et les portées plus en détail.