MCP dans Claude Code : ajouter et gérer des serveurs

Pour configurer MCP dans Claude Code, lancez claude mcp add dans le terminal. Un serveur local s’ajoute avec claude mcp add <nom> -- <commande>, un serveur distant avec claude mcp add --transport http <nom> <url>, et --scope décide si le serveur est réservé à vous dans ce projet (local, la valeur par défaut), partagé avec toute l’équipe via un fichier .mcp.json (project), ou disponible pour vous dans tous vos projets (user). Tapez ensuite /mcp dans une session pour vérifier la connexion et vous connecter aux serveurs qui utilisent OAuth.

Ce guide passe en revue chaque étape : transports, séparateur --, variables d’environnement et en-têtes, scopes, écriture de .mcp.json à la main, commandes list, get et remove, OAuth, import depuis Claude Desktop, timeouts et limites de sortie, et ce qu’il faut vérifier avant de faire confiance aux serveurs d’un projet. Les commandes proviennent de la documentation MCP de Claude Code d’Anthropic, à jour en octobre 2026. Si MCP est nouveau pour vous, commencez par ce qu’est un serveur MCP ; pour savoir quels serveurs ajouter, voyez les meilleurs serveurs MCP pour coder.

Mémo rapide

Les options courtes fonctionnent aussi : -t pour --transport, -s pour --scope, -e pour --env et -H pour --header.

Choisir un transport : stdio, HTTP ou SSE

Un serveur MCP rejoint Claude Code de l’une de ces trois façons :

Vous n’avez presque plus besoin de --transport sse. Depuis Claude Code 2.1.265, claude mcp add --transport http essaie d’abord HTTP et bascule tout seul sur SSE si le serveur n’accepte pas HTTP. Sur les versions plus anciennes, passez --transport sse explicitement.

Ajouter un serveur stdio local

La règle qui piège le plus de monde : les options de Claude Code (--transport, --scope, --env) se placent avant le nom du serveur, et tout ce qui suit -- est la commande du serveur, transmise telle quelle.

# Forme de base
claude mcp add [options] <nom> -- <commande> [arguments...]

# Playwright, lancé avec npx
claude mcp add playwright -- npx -y @playwright/mcp@latest

# Un serveur qui attend une clé d’API dans son environnement
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
  -- npx -y airtable-mcp-server

Sans --, une option du serveur comme --port 8080 serait lue comme une option de Claude Code et la commande échouerait. Autre piège signalé par la documentation : --env accepte plusieurs paires KEY=value, donc si le nom du serveur suit directement, il est lu comme une paire de plus et rejeté. Intercalez une autre option, par exemple --transport stdio, comme dans l’exemple ci-dessus.

Claude Code définit CLAUDE_PROJECT_DIR dans l’environnement de chaque serveur stdio, ce qui permet au serveur de trouver la racine du projet sans dépendre du répertoire de travail.

Ajouter un serveur HTTP distant

Un serveur distant prend une URL au lieu d’une commande. Ajoutez des en-têtes avec --header quand le serveur exige une clé d’API ou un bearer token :

# Un serveur hébergé avec connexion OAuth
claude mcp add --transport http notion https://mcp.notion.com/mcp

# Un serveur qui prend un token statique
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

Un en-tête saisi ici est stocké en clair dans le fichier de configuration. Pour tout ce qui est partagé, préférez OAuth ou une référence ${VAR} dans .mcp.json, détaillée plus bas.

Si le README d’un serveur fournit déjà une définition JSON, oubliez les options et collez-la avec add-json. La commande prend l’objet qui irait dans mcpServers, pas le fichier entier :

claude mcp add-json example '{"command":"npx","args":["-y","@example/mcp-server"]}'

Choisir un scope

Chaque claude mcp add écrit dans l’un de trois scopes :

claude mcp add --transport http stripe https://mcp.stripe.com                      # local
claude mcp add --transport http shared-server --scope project https://example.com/mcp
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

Règle simple : les outils personnels et tout ce qui porte vos propres identifiants vont dans user ou local ; les serveurs dont toute l’équipe a besoin pour travailler sur le dépôt vont dans project.

Attention, « local » ne désigne pas ici .claude/settings.local.json. Les serveurs MCP locaux sont dans ~/.claude.json, dans votre dossier personnel.

Quand un même nom est défini à plusieurs endroits, Claude Code garde la définition la plus prioritaire sans fusionner les champs : local d’abord, puis project, puis user, puis les serveurs de plugins, puis les connecteurs claude.ai. Si deux scopes associent le même nom à des endpoints différents, claude mcp list et /mcp vous avertissent.

Écrire .mcp.json à la main

Un serveur de scope project n’est rien d’autre qu’un fichier .mcp.json que vous pouvez modifier et relire en pull request :

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"]
    },
    "api-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    }
  }
}

${VAR} est remplacé par la valeur d’une variable d’environnement, et ${VAR:-default} utilise une valeur par défaut si elle manque. L’expansion fonctionne dans command, args, env, url et headers : c’est ainsi qu’on committe le fichier sans committer de tokens, chaque développeur définissant API_KEY dans son propre shell. Si une variable manque et n’a pas de valeur par défaut, claude mcp list et /mcp le signalent et laissent le texte tel quel.

Un "timeout" par serveur, en millisecondes, fixe une limite stricte pour les appels d’outils de ce serveur.

Gérer les serveurs : list, get, remove et /mcp

Depuis le shell :

claude mcp list          # tous les serveurs, avec leur état de connexion
claude mcp get notion    # détails d’un serveur, y compris la cause d’un échec
claude mcp remove notion # le supprime de son scope

list et get affichent le détail de l’erreur en masquant les identifiants. Un serveur de projet pas encore approuvé apparaît en attente jusqu’à ce que vous lanciez claude en mode interactif et l’approuviez.

Dans une session, /mcp est le tableau de bord. Il affiche l’état et le nombre d’outils de chaque serveur, et le menu d’un serveur permet de s’authentifier, de se réauthentifier, d’effacer l’authentification, de reconnecter ou de désactiver le serveur sans supprimer sa configuration. /mcp reconnect all relance d’un coup tous les serveurs en échec (Claude Code 2.1.284 ou plus récent).

Un serveur connecté apporte plus que des outils. Tapez @ pour référencer ses ressources à côté de vos fichiers, et / pour voir ses prompts, listés sous la forme /serveur:prompt (MCP). Les outils s’appellent mcp__<serveur>__<outil> : c’est ce nom que vous utilisez dans les règles de permissions et dans les matchers de hooks.

Se connecter aux serveurs OAuth

Beaucoup de serveurs hébergés, comme Sentry, Notion ou Linear, utilisent OAuth plutôt qu’un token statique. Ajoutez le serveur avec --transport http et sans en-tête, puis connectez-vous :

claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

Dans Claude Code, lancez /mcp, choisissez le serveur puis Authenticate. Le navigateur s’ouvre, vous vous connectez, et Claude Code stocke le token et le renouvelle. Vous pouvez aussi le faire depuis le shell sans ouvrir de session :

claude mcp login sentry               # ouvre le navigateur
claude mcp login sentry --no-browser  # affiche l’URL, pour les sessions SSH
claude mcp logout sentry              # oublie les identifiants stockés

Les exécutions headless (claude -p) ne peuvent pas afficher d’écran de connexion : connectez-vous d’abord une fois en mode interactif. Certains serveurs exigent un port de callback fixe ou une application OAuth préenregistrée ; pour ceux-là, passez --callback-port, --client-id et --client-secret à l’ajout du serveur. Le secret est demandé en saisie masquée, ou lu depuis MCP_CLIENT_SECRET en CI.

Importer des serveurs depuis Claude Desktop

Si vous avez déjà configuré des serveurs dans l’application Claude Desktop, inutile de les ressaisir :

claude mcp add-from-claude-desktop

Une boîte de dialogue vous laisse choisir les serveurs à importer. En octobre 2026, cela ne fonctionne que sur macOS et dans WSL. Ajoutez --scope user pour les importer dans votre configuration utilisateur. Les noms ne peuvent contenir que des lettres, des chiffres, des tirets et des underscores : un serveur Desktop dont le nom contient une espace est ignoré et signalé, et un nom déjà existant reçoit un suffixe comme server_1.

Dépannage

Les longs résultats texte ont une deuxième limite : un résultat de plus de 50 000 caractères est enregistré dans un fichier au lieu d’entrer directement dans le contexte.

Un serveur distant qui décroche en cours de session est relancé jusqu’à cinq fois avec un délai croissant, mais les serveurs stdio ne sont pas relancés automatiquement : un serveur local planté se reconnecte depuis /mcp.

Le contexte est l’autre coût à surveiller. Sur les modèles actuels, Claude Code utilise par défaut la recherche d’outils (tool search) : au démarrage, seuls les noms d’outils et les instructions des serveurs sont chargés, les définitions complètes l’étant quand Claude en a besoin. Une longue liste de serveurs reste donc peu coûteuse, mais chaque serveur est un élément de plus qui peut tomber en panne ou être détourné : gardez la liste courte. Pour les scripts, --mcp-config <fichier> charge des serveurs supplémentaires pour une seule exécution, et --strict-mcp-config force Claude Code à n’utiliser que ceux-là.

Sécurité : les serveurs de projet sont du code du dépôt

Un .mcp.json dans un dépôt peut lancer n’importe quelle commande locale ou pointer vers n’importe quelle URL. C’est ce qui le rend utile aux équipes, et c’est aussi pourquoi Claude Code s’en méfie :

• D’abord l’approbation. En session interactive, Claude Code demande avant d’utiliser les serveurs de scope project. claude mcp reset-project-choices efface vos réponses précédentes.
• Un dépôt ne peut pas s’approuver lui-même. Des réglages comme enableAllProjectMcpServers committés dans le .claude/settings.json du projet sont ignorés tant que vous ne faites pas confiance au dossier, et le serveur reste en attente. Les approbations de vos propres réglages utilisateur restent valables.
• Les exécutions headless ne demandent rien. Avec claude -p et l’Agent SDK, il n’y a pas d’invite : les serveurs de projet se chargent sans. Pour bloquer un serveur dans tous les modes, ajoutez-le à disabledMcpjsonServers.
• Les identifiants restent chez vous. Dans les champs url et headers d’un serveur distant, les variables sensibles comme ANTHROPIC_API_KEY sont remplacées par une valeur vide même si elles sont définies : un projet ne peut pas envoyer discrètement votre clé Anthropic à son serveur.
• Méfiez-vous autant de ce qu’un serveur renvoie que de ce qu’il exécute. La documentation d’Anthropic prévient que les serveurs qui récupèrent du contenu externe peuvent vous exposer à la prompt injection. Préférez les modes en lecture seule et des tokens aux droits restreints.

Avant d’approuver, lisez le command, les args et l’url de chaque serveur comme vous liriez un script postinstall. Pour la vue d’ensemble, voyez la sécurité des agents de code IA.

Si vous utilisez plus que Claude Code

Tout ce qui précède vaut pour une seule CLI. Codex garde ses serveurs dans ~/.codex/config.toml, Gemini CLI dans son propre settings.json, et chaque outil a ses propres commandes. Si Claude Code est votre seul agent, claude mcp add et un .mcp.json committé suffisent, et rien ici n’exige un autre outil.

Si vous faites tourner plusieurs CLI de code, les listes finissent par diverger. C’est le problème que traite le gestionnaire MCP d’AgentVera, l’application de bureau qui publie ce blog :

• Ajouté une fois, connecté au lancement. Vous enregistrez des serveurs stdio, HTTP et SSE dans AgentVera, et ils se connectent au démarrage des agents : à tous les agents, à ceux que vous choisissez, aux agents d’un groupe ou à un rôle d’équipe. Claude Code, Codex et les autres agents CLI compatibles MCP les reçoivent.
• En phase avec la configuration de Claude Code. Les serveurs des réglages de Claude Code et de Codex sont listés avec leur état ; vous pouvez les importer dans AgentVera ou les retirer de la CLI, et les serveurs d’AgentVera peuvent aussi être écrits dans les réglages de la CLI.
• Une seule connexion, aucun token dans les fichiers. Les serveurs distants passent par la passerelle d’AgentVera, vous vous connectez une fois dans l’application à un serveur OAuth, et la CLI de l’agent ne détient ni en-tête ni token. Les variables d’environnement et en-têtes secrets sont conservés dans le trousseau du système d’exploitation.
• Des coûts visibles. Un test de connexion liste les outils, prompts et ressources d’un serveur avec un coût approximatif en tokens par outil.

En résumé

Commencez par un serveur dont vous avez vraiment besoin, ajouté avec claude mcp add dans le scope le plus étroit possible. Vérifiez-le avec claude mcp list ou /mcp, connectez-vous avec /mcp ou claude mcp login, et ne le déplacez dans un .mcp.json committé que lorsque toute l’équipe en a besoin, avec les tokens dans des références ${VAR}. Quand quelque chose casse, claude mcp get, MCP_TIMEOUT et MAX_MCP_OUTPUT_TOKENS règlent l’essentiel.

Pour aller plus loin :

• Qu’est-ce qu’un serveur MCP ?
• Les meilleurs serveurs MCP pour les agents de code
• Gestionnaire MCP
• L’agent Claude Code