Où se trouvent les fichiers de configuration MCP de Claude Code et que contiennent-ils

Vous lancez claude mcp add, le serveur se connecte, puis une semaine plus tard un coéquipier vous demande où ce paramètre est passé. Claude Code ne conserve pas la configuration MCP dans un seul fichier bien rangé. Il la répartit entre ~/.claude.json, un .mcp.json au niveau du projet, plusieurs fichiers settings.json et, dans les configurations d’entreprise, un fichier de politique géré. Si vous modifiez le mauvais, rien ne change. Si vous modifiez le bon sans connaître l’ordre de priorité, une autre définition l’emporte discrètement.

Cet article répertorie chaque emplacement sous macOS, Windows et Linux, montre quelle définition l’emporte lorsque deux fichiers nomment le même serveur, et liste les commandes, les variables d’environnement et les paramètres de délai qui comptent au quotidien. Chaque chemin et chaque option ci-dessous ont été vérifiés dans la documentation actuelle de Claude Code ; vous pouvez donc les copier tels quels.

Où se trouvent réellement les fichiers

Claude Code propose trois portées pour les serveurs que vous ajoutez vous-même, auxquelles s’ajoute une couche organisationnelle qui les surplombe. La portée détermine deux choses : quels projets chargent le serveur, et si la définition est partagée avec le dépôt.

Trois portées, trois emplacements

La portée locale est celle par défaut. Un serveur ajouté sans --scope n’est chargé que dans le projet où vous avez lancé la commande, et reste privé. Claude Code l’écrit dans ~/.claude.json sous le chemin de ce projet :

{
  "projects": {
    "/path/to/your/project": {
      "mcpServers": {
        "stripe": {
          "type": "http",
          "url": "https://mcp.stripe.com"
        }
      }
    }
  }
}

Copier le prompt

La portée projet écrit un fichier .mcp.json à la racine du dépôt. Il est conçu pour être versionné, afin que chaque membre de l’équipe dispose des mêmes outils. La portée utilisateur conserve la définition dans le même fichier ~/.claude.json, en dehors de tout chemin de projet, si bien que chaque projet que vous ouvrez en tient compte.

💡 Règle rapide : un serveur privé ou expérimental relève de la portée locale. Un outil d’équipe partagé relève de la portée projet. Un outil personnel que vous voulez dans chaque dépôt relève de la portée utilisateur.

Chemins sous Windows, macOS et Linux

Sous Windows, ~ correspond à %USERPROFILE%, donc le fichier au niveau utilisateur est %USERPROFILE%\.claude.json. Le fichier .mcp.json est relatif à la racine de votre projet sur tous les systèmes. Seul le fichier géré change selon le système d’exploitation, car il se trouve dans un répertoire à l’échelle du système que contrôle un administrateur.

Si vous voulez placer les fichiers du répertoire personnel ailleurs, définissez CLAUDE_CONFIG_DIR. Claude Code y stocke alors vos paramètres, l’historique des sessions et les plugins, au lieu de ~/.claude.

Le piège du nom « local »

Le mot « local » a deux sens distincts dans Claude Code. La portée locale de MCP se trouve dans ~/.claude.json de votre répertoire personnel. Les paramètres locaux généraux se trouvent dans .claude/settings.local.json à l’intérieur du projet. Chercher settings.local.json pour un serveur MCP ajouté avec la portée par défaut ne donne rien, et cette seule confusion explique une grande part des questions du type « où est passé mon serveur ».

💡 Les définitions de serveurs vont dans .mcp.json ou ~/.claude.json, et les commandes claude mcp les écrivent à votre place. Les fichiers settings.json contiennent les approbations, les listes d’autorisation et les listes de refus, dont il est question plus bas.

À l’intérieur du fichier .mcp.json

Lorsque vous ajoutez un serveur avec --scope project, Claude Code crée ou met à jour ce fichier automatiquement. Vous pouvez aussi l’écrire à la main et le versionner. Il contient un champ d’enveloppe, mcpServers, et une entrée par serveur.

Un exemple fonctionnel

{
  "mcpServers": {
    "docs-search": {
      "type": "http",
      "url": "https://example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${SERVICE_TOKEN}"
      }
    },
    "local-files": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@example/files-server"],
      "env": {
        "ROOT_DIR": "${PROJECT_ROOT:-.}"
      },
      "timeout": 600000
    }
  }
}

Copier le prompt

Le champ type accepte http, sse, stdio et ws. Le nom streamable-http sert d’alias pour http, ce qui signifie qu’un extrait copié depuis la documentation d’un serveur se charge généralement sans modification. Une entrée stdio demande command, ainsi que args et env facultatifs. Une entrée distante demande url, ainsi que headers facultatif.

Un détail fait souvent trébucher les utilisateurs lorsqu’ils collent une configuration venant d’un autre client, comme Claude Desktop. La même enveloppe mcpServers fonctionne dans .mcp.json, mais claude mcp add-json attend uniquement l’objet à l’intérieur de l’enveloppe, et non l’enveloppe elle-même.

Des variables d’environnement plutôt que des secrets

Comme .mcp.json est versionné, les jetons n’y ont jamais leur place. Claude Code développe deux formes de référence à une variable :

• ${VAR} est remplacé par la valeur de VAR.
• ${VAR:-default} est remplacé par VAR lorsqu’elle est définie, et par default sinon.

La substitution fonctionne dans les valeurs command, args, env, url et headers. Si une variable n’est pas définie et n’a pas de valeur par défaut, le fichier se charge quand même. Claude Code affiche un avertissement de variable manquante pour ce serveur dans claude mcp list et utilise tel quel le texte brut ${VAR}, ce qui explique pourquoi un serveur peut échouer avec une chaîne littérale déroutante dans son en-tête.

Il existe aussi une règle de sécurité. Dans les url et headers d’un serveur distant, les variables qui portent des identifiants, comme ANTHROPIC_AUTH_TOKEN et NPM_TOKEN, sont lues comme vides. Cela empêche un dépôt cloné d’envoyer vos identifiants Claude Code ou cloud à un serveur qu’il désigne.

💡 Exportez le vrai jeton dans le profil de votre shell ou dans votre gestionnaire de secrets, et ne versionnez que la référence ${SERVICE_TOKEN}.

Ajouter des serveurs depuis le terminal

Vous avez rarement besoin de modifier le JSON vous-même. La famille claude mcp add écrit dans le bon fichier selon la portée choisie, et c’est le moyen le plus sûr d’éviter une faute de frappe qui casserait ~/.claude.json.

Commandes HTTP et stdio

# Remote HTTP server with a bearer token
claude mcp add --transport http docs-search https://example.com/mcp \
  --header "Authorization: Bearer your-token"

# Local stdio server. The -- separates Claude's options from the server command
claude mcp add --transport stdio --env SERVICE_TOKEN=abc123 local-files -- npx -y @example/files-server

# Shared with the team and written to .mcp.json
claude mcp add --scope project --transport http docs-search https://example.com/mcp

Copier le prompt

Pour les serveurs stdio, le double tiret est obligatoire. Tout ce qui précède appartient à Claude Code, et tout ce qui suit constitue la commande qui lance le serveur.

Les serveurs distants utilisent http ou sse, tandis qu’un processus local utilise stdio. Les serveurs WebSocket n’ont pas d’option dédiée, vous les ajoutez donc en JSON :

claude mcp add-json events-server '{"type":"ws","url":"wss://example.com/events"}'

Copier le prompt

Les serveurs qui utilisent OAuth prennent --client-id, --client-secret et --callback-port, et claude mcp login <name> vous connecte depuis la ligne de commande.

Vérifier ce qui s’est connecté

Trois commandes répondent à la plupart des questions : claude mcp list affiche tous les serveurs, claude mcp get <name> en affiche un seul, et claude mcp remove <name> en supprime un. Dans une session, /mcp ouvre la même vue et vous permet de vous authentifier.

Quelle définition l’emporte

Lorsque le même serveur apparaît à plusieurs endroits, Claude Code s’y connecte une seule fois et utilise la source de priorité la plus élevée.

La priorité, de la plus haute à la plus basse

1. Un serveur issu du paramètre géré managedMcpServers (Claude Code v2.1.259 ou ultérieure)
2. La portée locale
3. La portée projet
4. La portée utilisateur
5. Les serveurs fournis par les plugins
6. Les connecteurs claude.ai

Claude Code repère les doublons entre les trois portées par nom. Il repère les plugins et les connecteurs par point de terminaison : un élément qui pointe vers la même URL ou la même commande qu’un serveur activé situé au-dessus de lui compte comme un doublon.

Le détail le plus important : c’est l’entrée entière de la source gagnante qui est utilisée, et les champs ne sont pas fusionnés. Imaginons que docs-search existe dans la portée utilisateur avec un en-tête Authorization, et de nouveau dans la portée projet sans cet en-tête. La définition du projet l’emporte entièrement, et l’en-tête de l’entrée utilisateur n’apparaît jamais.

Demandes d’approbation pour les serveurs partagés

Pour des raisons de sécurité, Claude Code demande une approbation dans les sessions interactives avant d’utiliser un serveur de portée projet provenant de .mcp.json. Trois paramètres contrôlent le résultat :

{
  "enabledMcpjsonServers": ["docs-search"],
  "disabledMcpjsonServers": ["local-files"]
}

Copier le prompt

Vous avez fait un choix que vous regrettez ? claude mcp reset-project-choices efface les approbations.

Depuis la v2.1.196, un dépôt cloné ne peut pas approuver ses propres serveurs. Les approbations versionnées dans le fichier .claude/settings.json du projet sont ignorées dans un dossier non approuvé, et le serveur reste à ⏸ Pending approval. Les approbations de votre fichier de paramètres utilisateur, ~/.claude/settings.json, celles des paramètres gérés et celles de --settings restent valables. Un fichier .claude/settings.local.json non suivi fonctionne aussi, une fois le dossier approuvé.

Les exécutions non interactives, comme claude -p, chargent les serveurs de projet sans demander confirmation, sauf si vous les lancez avec --strict-mcp-config. Cette option indique à Claude Code de n’utiliser que les serveurs transmis avec --mcp-config.

💡 Relisez .mcp.json dans une pull request comme vous relisez un script. Une entrée stdio exécute une commande sur la machine de chaque coéquipier.

Fichiers de paramètres et contrôles de politique

Fichiers de paramètres, du plus prioritaire au moins prioritaire

Un paramètre défini à un niveau supérieur remplace le même paramètre défini plus bas. ~/.claude.json est un fichier distinct que Claude Code écrit pour lui-même. Il contient votre session de connexion, vos configurations de serveurs MCP, l’état de chaque projet, comme les décisions de confiance, ainsi que les options globales que modifie /config. Vous n’avez pas besoin de le modifier à la main.

Listes d’autorisation et serveurs gérés

Les équipes qui ont besoin de contrôle disposent de quatre outils, classés ici du plus souple au plus strict :

• disabledMcpServers permet à un utilisateur de désactiver certains serveurs utilisateur, plugin, gérés ou claude.ai.
• allowedMcpServers et deniedMcpServers filtrent par nom de serveur ou selon un motif serverUrl.
• managedMcpServers est un paramètre géré qui fournit des serveurs à tout le monde, en plus de ceux que les utilisateurs ajoutent.
• managed-mcp.json déploie un ensemble fixe de serveurs depuis les chemins système indiqués plus haut.

Déployer managed-mcp.json a un effet secondaire qui mérite d’être connu. Par défaut, il supprime les connecteurs claude.ai que Claude Code récupère lui-même. Pour les charger en plus de vos serveurs gérés, définissez "allowAllClaudeAiMcps": true dans une source de paramètres gérés. Définir la variable d’environnement ENABLE_CLAUDEAI_MCP_SERVERS=false désactive les connecteurs pour une seule machine.

Délais et limites de sortie

Délais de démarrage et d’outils

Deux minuteries comptent, et on les confond facilement.

Le paramètre timeout propre à chaque serveur remplace la variable d’environnement MCP_TOOL_TIMEOUT pour ce seul serveur. Les valeurs inférieures à 1000 sont ignorées et on retombe sur MCP_TOOL_TIMEOUT. Lorsque cette variable n’est pas définie, la valeur par défaut est d’environ 28 heures. Les notifications de progression envoyées par le serveur ne prolongent pas la limite.

Sortie volumineuse d’un outil

Claude Code affiche un avertissement lorsqu’un outil MCP renvoie plus de 10 000 tokens et limite la sortie à 25 000 tokens par défaut. Vous pouvez relever cette limite avec MAX_MCP_OUTPUT_TOKENS=50000 claude, ou la rendre permanente via le champ env d’un fichier de paramètres :

{
  "env": {
    "MCP_TIMEOUT": "10000",
    "MAX_MCP_OUTPUT_TOKENS": "50000"
  }
}

Copier le prompt

Corriger rapidement une configuration cassée

Symptômes et correctifs

Si ~/.claude.json ne peut pas être analysé, Claude Code copie le fichier défectueux vers ~/.claude/backups/.claude.json.corrupted.<timestamp> et vous demande s’il faut quitter pour le corriger à la main ou rétablir la configuration par défaut. Pour revenir à un état antérieur, copiez l’un des cinq fichiers .claude.json.backup.<timestamp> les plus récents depuis ~/.claude/backups/ à l’emplacement d’origine.

💡 Les modifications manuelles de ~/.claude.json valent rarement le risque. Privilégiez claude mcp add, add-json et remove, et gardez une copie du fichier avant toute modification manuelle.

Créez vos propres visuels avec Picasso IA

Le travail de configuration s’achève dès qu’un serveur affiche ✔ Connected, mais le documenter prend plus de temps que le faire. Les captures d’écran pour le README, les schémas d’intégration et les courtes vidéos d’une session de terminal ralentissent une équipe. C’est là que Picasso IA vous aide, avec des modèles de texte, d’image et de vidéo réunis au même endroit.

Utiliser Claude Sonnet 5 sur PicassoIA

Claude Sonnet 5 est un grand modèle de langage conçu pour le code et les tâches d’utilisation d’outils, ce qui le rend pratique pour rédiger une entrée de configuration ou la relire avant de la versionner. La page du modèle expose les champs suivants :

1. Ouvrez la page du modèle et collez votre demande dans Prompt. Par exemple : « Convertissez cette commande claude mcp add en entrée .mcp.json dont l’en-tête Authorization lit sa valeur depuis une variable d’environnement. »
2. Réglez Effort. La valeur par défaut est low, qui désactive la réflexion pour obtenir la réponse la plus rapide et la moins chère. Choisissez high ou max lorsqu’un bogue touche plusieurs fichiers.
3. Ajoutez un System Prompt du type « Répondez uniquement avec du JSON valide, sans commentaire » et réutilisez-le pendant toute la session.
4. Ne touchez pas à Max Tokens sauf si la sortie est longue. La valeur par défaut est 8 192.
5. Joignez une image si vous avez une capture d’écran d’une erreur. Le modèle la lit comme contexte.
6. Lancez-le, puis vérifiez. Collez le résultat dans .mcp.json et exécutez claude mcp get <name> pour confirmer que le serveur s’est connecté.

💡 Considérez la configuration générée comme un brouillon. Les chemins, les options et les paramètres changent d’une version à l’autre, vérifiez donc chacun d’eux dans la documentation officielle.

Pour la partie visuelle, des modèles de texte vers image comme PicassoIA Image et Seedream 5 Pro peuvent produire l’illustration d’en-tête d’une page de documentation ou d’un billet de changelog. Pour retoucher une image que vous possédez déjà, ouvrez PicassoIA Image Editor Pro. Pour le mouvement, PicassoIA Video et Seedance 2.5 Lite transforment un prompt ou une image fixe en courte vidéo.

PicassoIA propose aussi des connexions MCP pour ses modèles d’image et de vidéo, gérées depuis votre compte sur picassoia.com/en/mcp/accounts. Une fois les informations de connexion en main, un serveur HTTP s’ajoute avec le même motif claude mcp add --transport http que celui présenté plus haut.

Choisissez un modèle, rédigez un prompt et générez votre première image d’en-tête ou votre premier clip pour votre prochain README. Essayez plusieurs variantes, comparez-les côte à côte et gardez celle qui convient. Tout vous attend sur picassoia.com/en/all-models.