# Claude Code MCP : comment le configurer

> Brancher un serveur MCP sur Claude Code tient en une commande. Ce qu'on ne vous dit pas, c'est que chaque serveur connecté vous est facturé à chaque tour.

Source: https://tokenade.net/fr/articles/claude-code-mcp-setup · Updated: 2026-10-16

## 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](https://tokenade.net/fr/glossary/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 :

```bash
# 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.

```json
{
  "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 :

```json
"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 :

1. **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.
2. **`/context` en début de session, avant d'avoir tapé quoi que ce soit.** Ce qui occupe déjà votre [fenêtre de contexte](https://tokenade.net/fr/glossary/context-window) 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](https://tokenade.net/fr/articles/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](https://tokenade.net/fr) 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. La compaction s'exécute entièrement sur votre machine — rien de votre code n'est envoyé pour analyse. Il est gratuit et open source (MIT/Apache-2.0) : [installez-le](https://tokenade.net/fr/docs/install) et voyez 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](https://tokenade.net/fr/articles/best-mcp-servers-for-claude-code) 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](https://tokenade.net/fr/articles/token-efficient-mcp-tool-use) 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](https://tokenade.net/fr/articles/reduce-ai-coding-agent-token-usage) sont agnostiques à l'agent.

---

**Voir aussi :**
- [Meilleurs serveurs MCP Claude Code, classés au coût réel](https://tokenade.net/fr/articles/best-mcp-servers-for-claude-code) — lesquels méritent leur surcoût permanent.
- [Lazy MCP loading](https://tokenade.net/fr/articles/lazy-mcp-loading) — le correctif structurel des manifestes inactifs.
- [Utilisation des outils MCP économe en tokens](https://tokenade.net/fr/articles/token-efficient-mcp-tool-use) — réduire le coût des schémas et des sorties.
- [Serveurs MCP : ce qu'ils sont et ce qu'ils coûtent](https://tokenade.net/fr/articles/mcp-servers-explained) — la vue d'ensemble, tous agents confondus.
- [Serveur MCP GitHub : installation et coût réel](https://tokenade.net/fr/articles/github-mcp-server) — toolsets, mode read-only, et allègement du manifeste.
- [MCP (Model Context Protocol)](https://tokenade.net/fr/glossary/mcp) — ce qu'est le protocole, en une page.
- [Comment réduire la consommation de tokens de Claude Code](https://tokenade.net/fr/articles/reduce-claude-code-token-usage) — le pilier dont cet article dérive.