Claude Code et MCP : connecter vos outils

Connecter un outil à Claude Code tient en une commande, claude mcp add. Le temps se perd ensuite sur trois décisions que cette commande ne pose jamais : où vit la déclaration, où vit le secret, et quels outils l'agent peut appeler sans vous. Sur le serveur où travaillent nos agents de développement, trois serveurs MCP exposent 156 outils, dont une partie écrit dans des systèmes réels. Ces trois décisions y pèsent bien plus que l'installation.

Ce tutoriel s'adresse aux développeurs et aux équipes qui utilisent déjà Claude Code et savent à quoi sert le Model Context Protocol. Chaque commande a été rejouée le 1er novembre 2026 sur Claude Code 2.1.316, avec un serveur de test jetable et une configuration isolée. Deux résultats méritent votre attention avant le reste. Le CLI masque un jeton à l'écran tout en l'écrivant en clair dans le fichier destiné à git. Et claude -p lance le serveur d'un dépôt pendant que claude mcp list le déclare en attente d'approbation.

Ajouter un serveur MCP à Claude Code : les commandes qui suffisent

Un serveur distant s'ajoute avec --transport http, un serveur local avec --transport stdio, et les deux commandes se lancent dans le terminal, hors de toute session. Il vous faut Claude Code à jour, un compte sur l'outil visé, et Node.js si le serveur s'exécute par npx. La documentation MCP de Claude Code recommande HTTP pour un service en ligne et marque SSE comme déprécié.

# Serveur distant, connexion OAuth
claude mcp add --transport http notion https://mcp.notion.com/mcp

# Serveur local lancé par npx, exemple de la documentation
claude mcp add --transport stdio --env AIRTABLE_API_KEY=VOTRE_CLE airtable \
  -- npx -y airtable-mcp-server

# Contrôle
claude mcp list
claude mcp get notion

Le double tiret sépare les options de Claude Code de la commande du serveur. Sans lui, un drapeau comme --port serait lu par Claude Code au lieu d'être transmis au serveur.

claude mcp list interroge les serveurs approuvés et rend leur état, à lire avant de croire l'installation terminée. Sur de vrais points d'entrée, sans identifiants, Notion et Sentry ont répondu Needs authentication. Cet état est normal : il reste à ouvrir /mcp dans une session pour suivre la connexion OAuth, ou à lancer claude mcp login notion depuis le terminal. Un serveur stdio joignable affiche Connected, et un serveur de .mcp.json encore non approuvé reste en Pending approval, sans être contacté.

L'ajout, lui, ne valide pas les identifiants. Nous avons enregistré un jeton volontairement faux et la commande a rendu un code de sortie 0. Il a fallu claude mcp list pour voir l'erreur HTTP 401. Un serveur ajouté sans ce contrôle peut donc rester cassé jusqu'au jour où l'agent en a besoin.

Une fois connecté, un serveur apporte jusqu'à trois choses. Claude appelle ses outils de lui-même, vous mentionnez ses ressources avec @, et ses prompts deviennent des commandes de la forme /mcp__serveur__prompt. Les réglages qui suivent portent presque tous sur les outils.

Local, projet ou utilisateur : où Claude Code écrit votre serveur

Claude Code écrit le serveur dans ~/.claude.json en portée local ou user, et dans .mcp.json à la racine du dépôt en portée project. La portée par défaut, local, ne laisse donc aucune trace dans votre projet. Nous avons relevé le fichier réellement modifié pour chacune des trois.

Source : portées d'installation MCP, consulté le 01/11/2026, et fichiers relevés sur Claude Code 2.1.316.

Le piège vient du mot « local ». Il n'a aucun rapport avec .claude/settings.local.json, et la documentation prend la peine de le préciser. Le serveur atterrit dans ~/.claude.json, rangé sous le chemin absolu du projet. Cette clé a une conséquence que la commande ne signale pas. Après le renommage de notre dossier de test, le serveur ne figurait plus dans claude mcp list. Le même effet est à prévoir pour un projet déplacé ou cloné ailleurs, puisque la clé est le chemin.

Quand un même nom existe à plusieurs niveaux, Claude Code garde une seule définition, dans cet ordre : local, projet, utilisateur, plugins, puis connecteurs claude.ai. L'entrée retenue est prise entière, sans fusion de champs. Une entrée locale qui redéclare un serveur d'équipe pour changer son URL perd donc les en-têtes de la version partagée, sauf si vous les recopiez.

Relire .mcp.json ne montre pas non plus tout ce qu'une session charge. Les plugins Claude Code et les connecteurs d'un compte claude.ai ajoutent leurs serveurs sans toucher ce fichier, comme le rappelle la page sécurité. Notre règle tient en une phrase. Tout commence en local, et un serveur passe en project quand un deuxième développeur en a besoin et que sa déclaration ne porte aucun secret.

Le jeton d'un serveur MCP n'a rien à faire dans git

Un jeton passé avec --header en portée project part en clair dans .mcp.json, alors que le terminal l'affiche masqué. Or la documentation invite à versionner ce fichier. Notre essai avec un jeton fictif montre l'écart, sortie abrégée.

$ claude mcp add --transport http --scope project demo \
    https://mcp.example.com/mcp --header "Authorization: Bearer jeton-fictif-456"
Headers: { "Authorization": "[REDACTED]" }

$ cat .mcp.json
"headers": { "Authorization": "Bearer jeton-fictif-456" }

Le masquage ne couvre que l'affichage. En portée local, le même jeton et les valeurs de --env restent en clair, cette fois dans ~/.claude.json, hors du dépôt. Ce fichier était en droits 600 sur notre serveur Linux, et il reste la bonne place pour un jeton personnel. Pour un serveur partagé, la déclaration référence une variable et chaque développeur garde sa valeur dans son environnement.

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": { "Authorization": "Bearer ${GITHUB_PAT}" }
    }
  }
}

Nous avons vérifié l'expansion avec un serveur HTTP local qui notait l'en-tête reçu, et il a bien lu la valeur de la variable. Le cas inverse mérite plus d'attention, car une variable oubliée n'empêche pas le démarrage. Notre serveur stdio, lancé sans sa variable, a reçu le texte littéral ${NOX_TOKEN}, douze caractères à la place du jeton. La documentation décrit ce comportement : le serveur se charge quand même, et un avertissement nomme la variable dans claude mcp list, sous la forme Missing environment variables, et dans /mcp. La syntaxe ${VAR:-defaut} fournit une valeur de repli quand elle a du sens.

Certains serveurs refusent la connexion OAuth automatique de Claude Code. Sans jeton, le serveur distant de GitHub a rendu Failed to connect avec le motif does not support dynamic client registration. Ce refus n'a rien d'une panne, car le guide d'installation de GitHub prévoit un jeton d'accès personnel pour ce serveur. La documentation de Claude Code conseille un jeton à grain fin, limité aux dépôts utiles. Un en-tête Authorization coupe aussi le repli sur OAuth, comme l'indiquait le message d'erreur de notre essai à jeton faux.

Dernier piège de format, une entrée avec url et sans type est ignorée. La nôtre a disparu de la liste des serveurs, en ne laissant qu'un avertissement dans les diagnostics, et claude mcp get répondait qu'aucun serveur ne portait ce nom.

Combien de contexte coûte un serveur MCP dans Claude Code ?

Avec tool search, actif par défaut, les 156 outils de nos trois serveurs ajoutent environ 4 500 jetons à une session. Sans lui, ils en ajoutent environ 315 000. Nous avons relevé le total de jetons en entrée de claude -p sur une demande d'une ligne, modèle Haiku, chaque configuration jouée deux fois, avec un témoin sans aucun serveur. Les rejeux sont identiques au jeton près, le témoin varie d'un seul jeton, et chaque passage correspond à une seule requête API. Notre session annonçait une fenêtre d'un million de jetons : sans tool search, ces outils en occuperaient près d'un tiers avant le premier message.

Le coût par outil varie du simple au triple selon ce que déclare le serveur. Nos outils de test, décrits en une phrase avec quatre paramètres, pèsent environ 600 jetons pièce une fois chargés. Nos outils réels, aux schémas plus riches, en pèsent environ 2 000. La mesure confirme la documentation de tool search, qui ne charge au démarrage que les noms d'outils et les instructions du serveur.

Ce filet peut tomber sans bruit. La documentation liste les cas où les outils sont chargés d'emblée : ENABLE_TOOL_SEARCH=false, modèles antérieurs à Opus 4 et Sonnet 4, déploiements Microsoft Foundry hébergés sur Azure, et tout serveur marqué alwaysLoad: true. Derrière une passerelle LLM qui refuse le mécanisme, Claude Code peut aussi retomber sur un chargement complet sans rien afficher. La commande /context montre ce qui occupe réellement la place.

La seconde dépense arrive à l'appel. Claude Code avertit dès 10 000 jetons de sortie et plafonne par défaut à 25 000, réglage MAX_MCP_OUTPUT_TOKENS. Au-delà de 50 000 caractères de texte, le résultat part dans un fichier. Notre outil de test, qui renvoyait 60 000 caractères, n'a livré à Claude qu'un chemin de fichier à relire. Un serveur qui renvoie tout par défaut gagne donc à recevoir un filtre ou une pagination.

Un serveur lourd ou sensible peut aussi vivre dans un seul sous-agent. Le champ mcpServers de son fichier le déclare en ligne, et ses descriptions d'outils restent hors de la conversation principale.

Régler les droits d'un serveur MCP outil par outil

Une règle de permission vise un serveur entier, un préfixe ou un seul outil, et la bonne granularité dépend de ce que l'outil peut modifier. Les noms suivent la forme mcp__serveur__outil, documentée avec ses jokers. Une règle d'autorisation doit nommer un serveur précis, car mcp__* seul est ignoré.

{
  "permissions": {
    "allow": ["mcp__github__get_*", "mcp__github__list_*"],
    "ask": ["mcp__github__create_*"],
    "deny": ["mcp__github__delete_*"]
  }
}

Nous avons testé allow et deny en claude -p, mode manuel, avec le journal du serveur comme juge. Sans règle, l'appel y est refusé avant d'atteindre le serveur, là où une session interactive vous poserait la question. L'outil exact, un préfixe en get_*, le joker de serveur et le nom de serveur seul l'ont tous autorisé. Une règle sur un autre préfixe ne l'a pas autorisé, et un deny a battu un allow joker. La règle ask suppose une personne devant l'écran, et notre banc automatique ne l'a pas exercée.

Un premier passage nous a rappelé une limite. Lancé avec notre réglage habituel, defaultMode: auto, le même outil a été appelé sans aucune règle, parce que ce mode confie la décision à un classifieur. Notre outil de test était inoffensif, et nous n'avons pas mesuré ce que le classifieur ferait d'un outil d'écriture. L'absence de règle ne constitue donc pas une barrière dans ce mode, que la page sécurité présente comme le mode de départ des sessions interactives. Les règles deny et ask restent appliquées, et c'est là que nous plaçons les outils destructifs.

Le risque le plus sérieux combine lecture et écriture. La documentation avertit que les serveurs qui récupèrent du contenu externe exposent à l'injection de prompt : un ticket, un e-mail ou une page peut contenir des instructions que l'agent prendra pour les vôtres. Sur les outils qui touchent à l'argent ou aux clients, nous laissons l'agent préparer et un humain activer. Pour garder une trace, un hook PreToolUse avec le matcher mcp__noxtest__.* a reçu le nom complet de l'outil dans notre essai, de quoi journaliser chaque appel.

claude -p lance les serveurs d'un dépôt sans rien demander

En mode non interactif, Claude Code connecte les serveurs du .mcp.json d'un dépôt sans approbation, même dans un dossier jamais approuvé. Notre dépôt de test déclarait un serveur dont la commande écrit un fichier témoin au démarrage. claude mcp list l'affichait Pending approval, et le témoin restait absent. Un simple claude -p a suffi : la commande a tourné et le témoin est apparu.

Ce comportement est documenté, mais l'écart entre ce que dit la liste et ce que fait l'exécution surprend. Un serveur stdio est une commande lancée sur votre machine. Faire tourner claude -p sur un dépôt reçu, une pull request externe ou un code à auditer revient donc à exécuter ce que ce dépôt a déclaré. Deux options l'ont bloqué dans nos essais, et le témoin rejoué sans option a bien relancé le serveur.

# Ignore les réglages et le .mcp.json du dépôt
claude -p "Résume ce dépôt" --setting-sources user

# N'utilise que les serveurs listés dans votre fichier
claude -p "Résume ce dépôt" --strict-mcp-config --mcp-config ./mcp-ci.json

La documentation cite aussi --bare, présenté comme le mode recommandé pour les appels scriptés. Il n'utilise pas la connexion par abonnement : notre essai s'est arrêté sur Not logged in, et il lui faut une clé d'API, par exemple ANTHROPIC_API_KEY. Nous n'avons donc pas vérifié cette troisième parade, détaillée avec les autres risques de dépôt dans notre article sur la sécurité de Claude Code.

Une intégration continue a un second angle mort. Une entrée invalide de --mcp-config est sautée et le run se termine proprement, donc le pipeline tourne sans son serveur. La documentation du mode non interactif conseille de faire échouer le job sur le champ mcp_server_errors de l'événement system/init. Pour une organisation, managed-mcp.json fixe la liste des serveurs, et allowedMcpServers et deniedMcpServers filtrent ceux que les utilisateurs ajoutent. Anthropic précise qu'il examine les connecteurs de son annuaire sans auditer la sécurité d'aucun serveur MCP, et la confiance accordée à un serveur reste donc à votre charge.

Quel serveur MCP brancher, et quand s'en passer

Un serveur MCP se justifie quand aucune ligne de commande ne fait le travail, ou quand chaque utilisateur doit se connecter avec son propre compte. La documentation sur les coûts va dans ce sens : gh, aws, gcloud et sentry-cli restent plus économes en contexte, parce qu'ils n'ajoutent aucune liste d'outils. Sur notre serveur, GitHub passe donc par gh, et nous réservons MCP aux outils pour lesquels aucune commande ne fait l'affaire.

Le nombre de serveurs compte moins depuis tool search, mais chacun reste un secret, une dépendance et une surface d'attaque de plus à suivre. Notre méthode avec hooks, skills et MCP explique pourquoi nous en gardons trois au quotidien. Pour un outil interne, mieux vaut créer un serveur MCP limité à quelques actions que d'exposer une API entière. Pour une base de données, la documentation conseille un utilisateur en lecture seule, afin que les requêtes de Claude ne puissent rien modifier.

Connecter un outil pour soi reste à la portée de tout développeur. Le travail change d'échelle quand l'agent tourne pour une équipe entière ou atteint des données clients, avec une portée partagée, des secrets à distribuer, des droits par outil et une intégration continue à durcir. Notre agence agent IA pose ces réglages avec vous et les teste sur vos usages réels.

Questions fréquentes sur Claude Code et MCP

Comment vérifier que Claude Code voit mon serveur MCP ?

Lancez claude mcp list depuis le dossier du projet, car les portées local et project dépendent de ce dossier. Chaque serveur affiche son état : Connected, Needs authentication, Pending approval ou Failed to connect. La commande claude mcp get nom détaille sa portée et son type. Dans une session, /mcp donne le même état et permet de se connecter ou de reconnecter un serveur tombé.

Comment désactiver un serveur MCP sans le supprimer ?

Ouvrez /mcp dans une session et désactivez le serveur. Le choix est enregistré par projet dans ~/.claude.json, sous disabledMcpServers, et sa configuration reste intacte. Pour écarter un serveur de .mcp.json dans tous les types de session, claude -p compris, ajoutez son nom à disabledMcpjsonServers dans vos réglages. Notre essai en claude -p l'a confirmé : le serveur n'a pas démarré, alors que le témoin sans ce réglage démarrait.

Comment supprimer proprement un serveur connecté en OAuth ?

Lancez claude mcp logout nom avant claude mcp remove nom. La seconde commande efface les jetons et l'enregistrement stockés sur votre poste, sans les révoquer chez le serveur d'autorisation, d'après la documentation. Le jeton peut donc rester valable après la suppression. La révocation suppose en plus que le serveur d'autorisation la prenne en charge : contrôlez dans les réglages de l'outil que l'application connectée a bien disparu.

Un serveur MCP ajouté au terminal fonctionne-t-il dans VS Code ?

Oui, l'extension et le CLI partagent la même configuration MCP. Vous pouvez lancer claude mcp add dans le terminal intégré ou taper /mcp dans le panneau de discussion, et les deux écrivent au même endroit. Les changements s'appliquent aux conversations lancées ensuite, d'où l'intérêt d'en ouvrir une nouvelle après un ajout. L'installation complète figure dans notre guide Claude Code dans VS Code.

MCP, skill ou plugin, lequel utiliser ?

Prenez un serveur MCP quand Claude doit agir sur un système extérieur, comme une base de données, un outil de tickets ou une API. Une skill Claude Code convient pour transmettre un savoir-faire, chargé à la demande et sans aucune connexion. Un plugin sert à distribuer l'ensemble à une équipe, serveurs MCP compris. Les trois se combinent souvent dans une même configuration, et le plugin n'a d'intérêt que lorsque plusieurs personnes doivent partager ces réglages.