Claude Code MCP : comment le configurer

Comment ajouter un serveur MCP à Claude Code ?

On l'ajoute avec claude mcp add, et la forme exacte dépend du transport : claude mcp add --transport http <nom> <url> pour un serveur distant, ou claude mcp add <nom> -- <commande> [args...] pour un processus local en stdio. Voilà pour l'installation. La vraie question n'est pas comment brancher un serveur, mais ce qu'il vous coûte ensuite — et c'est précisément la partie que les guides de démarrage sautent. Je construis des outils de réduction de tokens, donc je regarde MCP sous un angle que la plupart des tutoriels ignorent : chaque serveur connecté annonce ses définitions d'outils au modèle, et il le fait à chaque tour, que vous appeliez un outil ou aucun. L'installation est un acte ponctuel. La facture, elle, est récurrente. Cet article traite les deux moitiés : la mécanique d'abord, complète et honnête, puis la comptabilité que personne ne publie. Les trois formes que vous utiliserez réellement :

# Serveur distant en HTTP
claude mcp add --transport http notion https://mcp.notion.com/mcp

# Serveur local en stdio (le séparateur -- est obligatoire)
claude mcp add airtable -- npx -y airtable-mcp-server

# Avec une variable d'environnement
claude mcp add --env AIRTABLE_API_KEY=cle airtable -- npx -y airtable-mcp-server

Ce séparateur -- compte : il indique à Claude Code où s'arrêtent ses propres options et où commence la commande du serveur. Sans lui, les flags de votre serveur sont interprétés comme ceux de Claude. Deux remarques sur les transports. SSE fonctionne encore, mais HTTP est désormais la forme recommandée pour les serveurs distants. Et WebSocket n'a aucun flag CLI : si vous avez besoin de type: "ws", il faut passer par claude mcp add-json avec une chaîne JSON brute.

Quel scope choisir : local, project ou user ?

Prenez --scope project pour tout ce dont vos collègues ont aussi besoin, --scope user pour les outils que vous voulez dans tous vos projets, et le local par défaut pour le reste. Le scope détermine le fichier dans lequel l'entrée atterrit, et donc qui d'autre en hérite.

Scope	Flag	Écrit dans	Qui le voit
Local (défaut)	`--scope local`	`~/.claude.json`, sous le projet courant	Vous, ici seulement
Project	`--scope project`	`.mcp.json` à la racine du projet	L'équipe, via le versioning
User	`--scope user`	`~/.claude.json`, au niveau racine	Vous, partout

Celui qui surprend, c'est user. Il est pratique — on branche une fois, c'est disponible dans tous les dépôts — et c'est aussi le moyen le plus rapide de payer le manifeste d'un serveur dans des projets qui n'en ont aucun usage. Un MCP de base de données chargé dans un dépôt de site statique, c'est du surcoût pur à chaque tour. Je réserve le scope user aux outils réellement universels et je fais redescendre tout le reste en project. Sous Windows, ~/.claude.json correspond à %USERPROFILE%\.claude.json. Si vous avez défini CLAUDE_CONFIG_DIR, c'est cette valeur qui l'emporte.

À quoi ressemble vraiment `.mcp.json` ?

.mcp.json se place à la racine du projet, se commite dans le versioning, et contient un unique objet racine mcpServers indexé par nom de serveur.

{
"mcpServers": {
"github": {
"type": "http",
"url": "https://api.githubcopilot.com/mcp/",
"headers": { "Authorization": "Bearer ${GITHUB_TOKEN}" }
},
"postgres": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-postgres"],
"env": { "DATABASE_URL": "${DATABASE_URL}" }
}
}
}

Les champs se répartissent par transport. Les entrées de la famille HTTP acceptent url, headers, et en option timeout (en millisecondes), oauth et headersHelper. Les entrées stdio acceptent command, args et env. Un piège mérite d'être connu : une entrée sans champ type est traitée comme du stdio. Combinez cet oubli avec un url et vous obtenez une erreur de configuration plutôt qu'un serveur fonctionnel — un échec déroutant la première fois qu'on le rencontre. Déclarez type explicitement et le problème n'arrive jamais. Comme .mcp.json est commité, Claude Code demande une approbation avant de faire confiance aux serveurs de scope project. Le garde-fou est sain : sans lui, une branche récupérée pourrait brancher un nouveau serveur dans votre session en silence. claude mcp reset-project-choices remet ces approbations à zéro si vous voulez redécider.

Comment passer des secrets sans les commiter ?

Utilisez l'expansion ${VAR} dans .mcp.json, pour que le fichier ne contienne que le nom du secret, jamais sa valeur. La syntaxe fonctionne dans url, headers, command, args et env, et gère les valeurs par défaut :

"url": "${API_BASE_URL:-https://api.example.com}/mcp",
"headers": { "Authorization": "Bearer ${API_TOKEN}" }

${VAR} substitue la variable d'environnement ; ${VAR:-defaut} prend le relais quand elle n'est pas définie. C'est ce qui rend un .mcp.json commité sûr : le token vit dans votre shell ou votre gestionnaire de secrets, et le dépôt ne porte que la référence. Pour les identifiants qui doivent être générés au moment de la connexion — tokens à durée de vie courte, requêtes signées — il y a headersHelper. Vous pointez vers un exécutable, il est lancé à chaque connexion avec un budget de 10 secondes, et il écrit sur stdout un objet JSON d'en-têtes. Claude Code lui transmet CLAUDE_CODE_MCP_SERVER_NAME et CLAUDE_CODE_MCP_SERVER_URL dans son environnement, de sorte qu'un seul script peut servir plusieurs serveurs. Pour les serveurs OAuth, il n'y a généralement rien à faire : les serveurs HTTP et SSE négocient OAuth 2.0 automatiquement, et le panneau /mcp vous guide dans la connexion via le navigateur. claude mcp login <nom> et claude mcp logout <nom> font la même chose en ligne de commande si vous préférez ne pas quitter le terminal.

Comment vérifier qu'un serveur est réellement connecté ?

Lancez claude mcp list depuis le shell, ou /mcp en session : les deux affichent chaque serveur configuré avec son état en direct. Les états méritent d'être appris, car ils échouent de façons vraiment différentes :

✔ Connected — fonctionnel.
! Connected · tools fetch failed — le transport est up mais la liste d'outils n'est pas revenue. Le serveur est joignable et inutile.
! Needs authentication — lancez claude mcp login <nom>, ou authentifiez-vous depuis le panneau /mcp.
✘ Failed to connect — injoignable. En général une mauvaise URL, une commande locale morte, ou une variable d'environnement manquante.
⏸ Pending approval — un serveur de scope project en attente de votre décision de confiance.

claude mcp get <nom> affiche la configuration résolue complète d'un serveur : c'est le moyen le plus rapide de découvrir que votre ${API_TOKEN} s'est substitué en chaîne vide. Le panneau /mcp porte un autre chiffre, plus important qu'on ne le croit : le nombre d'outils par serveur. C'est ce qui se rapproche le plus d'une étiquette de prix, et la section suivante explique pourquoi.

Que coûte chaque serveur connecté, à chaque tour ?

Les définitions d'outils de chaque serveur connecté sont envoyées au modèle à chaque tour : un serveur que vous n'appelez jamais vous est donc facturé tant qu'il reste branché. C'est le fait le plus important sur MCP, et les guides d'installation l'omettent systématiquement. Ce n'est pas un bug mais une conséquence structurelle — le modèle ne peut pas appeler un outil dont on ne lui a pas parlé. Ici je dois être direct, parce que c'est le point où la plupart des articles se mettent à inventer des chiffres : presque personne ne publie ce que coûte son manifeste. J'ai cherché. Des estimations tierces circulent largement pour les serveurs populaires et se contredisent de plusieurs dizaines de milliers de tokens — ce qui signale des mesures faites sur des versions différentes dans des conditions différentes, pas des faits. Je ne vais pas les répéter comme si elles en étaient. Ce qu'on peut obtenir, c'est l'ordre de grandeur, à partir de ce que les éditeurs publient vraiment. Le serveur MCP officiel de GitHub embarque 20 toolsets et expose 56 outils en lecture seule, avant de compter ceux en écriture — chaque schéma étant annoncé au modèle à chaque tour tant que vous ne restreignez pas l'ensemble. Pas besoin d'un chiffre en tokens pour voir qu'un manifeste de cette taille, renvoyé sur trente tours, n'est pas une erreur d'arrondi. Donc mesurez plutôt que de deviner. Deux lectures vous disent presque tout :

Le nombre d'outils dans /mcp. La taille du manifeste croît avec le nombre d'outils et la verbosité de leurs schémas. Un serveur qui expose 40 outils ne joue pas dans la même catégorie qu'un serveur qui en expose 4.
/context en début de session, avant d'avoir tapé quoi que ce soit. Ce qui occupe déjà votre fenêtre de contexte au tour zéro, c'est votre surcoût permanent. Branchez un serveur, redémarrez, regardez à nouveau : la différence est le prix réel de ce serveur sur votre installation.

Cette seconde mesure prend deux minutes et vaut mieux que n'importe quel chiffre que je pourrais citer, parce qu'elle porte sur vos serveurs dans leur version actuelle.

Comment garder les outils sans payer ceux qui dorment ?

En différant le manifeste : envoyer les définitions d'outils d'un serveur quand un outil est réellement appelé, au lieu de les précharger à chaque tour. C'est le lazy MCP loading, et c'est le correctif structurel plutôt qu'une discipline à se rappeler. La version manuelle relève de l'hygiène : branchez ce dont cette session a besoin, débranchez le reste, et préférez le scope project au scope user pour que les serveurs ne vous suivent pas dans des dépôts qui n'en veulent pas. Ça marche. Ça suppose aussi de le faire tous les jours, c'est-à-dire exactement le type de constance qui s'effrite sous la pression d'une deadline. Tokenade comble cet écart en chargeant les définitions d'outils MCP de façon paresseuse dans Claude Code — ainsi que Cursor, Codex, Copilot et Windsurf, puisque le problème du manifeste est identique partout — pour que les serveurs inactifs cessent de voyager sur chaque tour. Il compresse aussi ce que renvoient les outils bavards, qui est l'autre moitié de la facture MCP. C'est source-available sous licence MIT : vous pouvez lire exactement ce qu'il fait à votre contexte avant de lui confier une session, et l'offre gratuite suffit à voir si les chiffres bougent sur votre propre installation. Quelle que soit la voie choisie, le principe est le même : brancher un serveur devrait être une décision prise projet par projet, pas un défaut dont on hérite. Quels serveurs MCP méritent leur place déroule ce compromis serveur par serveur.

Les serveurs peuvent-ils apporter autre chose que des outils ?

Oui : un serveur peut aussi exposer des resources que vous référencez avec @ et des prompts qui apparaissent comme des slash commands — même si le support varie, chaque serveur choisissant ce qu'il implémente. Les resources s'autocomplètent quand vous tapez @, sous la forme @nomserveur:protocole://chemin/ressource — par exemple @github:issue://123 ou @postgres:schema://users. Claude Code récupère et attache la ressource quand vous la référencez. Le motif est réellement moins cher qu'un appel d'outil pour une lecture simple : vous tirez une chose précise au lieu de décrire une recherche. Les prompts apparaissent quand vous tapez /, sous la forme /mcp__nomserveur__nomprompt — /mcp__github__list_prs par exemple, avec les arguments séparés par des espaces. Ils sont découverts dynamiquement à partir de ce qui est connecté.

Ce qui tourne mal (anti-patterns)

Installer les serveurs en scope user par défaut. C'est le flag pratique, et le flag coûteux. Chaque projet que vous ouvrez paie pour chaque outil que vous avez branché un jour, y compris ceux qui n'ont rien à voir avec ce dépôt. Brancher un serveur « pour essayer » et ne jamais le débrancher. L'essai ne coûte rien. L'oubli coûte à chaque tour, indéfiniment, en silence. Se fier aux tailles de manifestes annoncées par des tiers. Elles se contredisent parce qu'elles mesurent des versions différentes. Mesurez la vôtre avec /context : deux minutes. Omettre type dans .mcp.json. Pas de type signifie stdio. Avec un url présent, c'est une erreur de configuration et une première session de débogage déroutante. Commiter des secrets dans .mcp.json. Le fichier est fait pour être commité. Utilisez l'expansion ${VAR} : le dépôt doit porter le nom du secret, jamais sa valeur. Juger un serveur au seul nombre d'outils. Dix outils concis peuvent coûter moins que quatre aux schémas tentaculaires. Le compte est un indice, /context est la mesure.

Foire aux questions

Quelle différence entre `.mcp.json` et `~/.claude.json` ?

.mcp.json se trouve à la racine du projet et est destiné à être commité : c'est ainsi qu'une équipe partage les mêmes serveurs. ~/.claude.json est votre fichier personnel : --scope local y écrit sous le projet courant, --scope user y écrit au niveau racine pour tous les projets. Règle simple : si un collègue qui clone le dépôt aurait besoin du serveur, sa place est dans .mcp.json.

Un serveur MCP coûte-t-il des tokens si je n'appelle jamais ses outils ?

Oui. Les définitions d'outils sont annoncées au modèle à chaque tour, qu'elles servent ou non — c'est ainsi que le modèle sait que les outils existent. Un serveur inactif est un coût permanent par tour, ce qui fait du débranchement des serveurs inutilisés l'un des gains les moins chers disponibles. L'utilisation des outils MCP économe en tokens traite en profondeur les côtés schéma et sortie.

Comment savoir ce qu'un serveur précis me coûte ?

Lancez /context dans une session fraîche avant de taper quoi que ce soit, notez le chiffre, branchez le serveur, redémarrez et comparez. La différence est le surcoût réel par tour de ce serveur sur votre machine dans sa version actuelle — plus fiable que n'importe quelle estimation publiée, puisque les manifestes changent d'une version à l'autre.

Pourquoi mon serveur de scope `project` affiche-t-il « pending approval » ?

Parce que .mcp.json est versionné, Claude Code demande confirmation avant de faire confiance aux serveurs qu'il y trouve — sinon, récupérer une branche pourrait brancher un nouveau serveur dans votre session à votre insu. Approuvez depuis le panneau /mcp ; claude mcp reset-project-choices efface les décisions passées si vous voulez tout réapprouver de zéro.

Puis-je utiliser les mêmes serveurs MCP dans Cursor ou Codex ?

En grande partie oui : MCP est un protocole partagé, donc un serveur écrit pour un agent fonctionne généralement dans un autre — chaque hôte diffère toutefois par son format de configuration et par les parties de la spécification qu'il implémente. Le coût du manifeste par tour, lui, se reporte à l'identique : c'est pourquoi les leviers de comment réduire la consommation de tokens des agents de codage IA sont agnostiques à l'agent.

Voir aussi :

Meilleurs serveurs MCP Claude Code, classés au coût réel — lesquels méritent leur surcoût permanent.
Lazy MCP loading — le correctif structurel des manifestes inactifs.
Utilisation des outils MCP économe en tokens — réduire le coût des schémas et des sorties.
Serveurs MCP : ce qu'ils sont et ce qu'ils coûtent — la vue d'ensemble, tous agents confondus.
Serveur MCP GitHub : installation et coût réel — toolsets, mode read-only, et allègement du manifeste.
MCP (Model Context Protocol) — ce qu'est le protocole, en une page.
Comment réduire la consommation de tokens de Claude Code — le pilier dont cet article dérive.