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

URL: https://agentvera.dev/fr/blog/claude-code-mcp-setup/ · Publié: 2026-10-28

Ajouter des serveurs MCP à Claude Code : claude mcp add en stdio et HTTP, scopes, .mcp.json, /mcp et OAuth, import depuis Claude Desktop, timeouts et limites.

**En bref:**

- On ajoute un serveur avec claude mcp add : les options passent avant le nom, et la commande d’un serveur stdio local après --. Les serveurs distants utilisent --transport http avec une URL.
- Le scope décide où il est stocké : local (par défaut) et user dans ~/.claude.json, project dans un .mcp.json à la racine du dépôt, que vous pouvez committer.
- Dans une session, /mcp affiche l’état, connecte les serveurs OAuth et désactive des serveurs. MCP_TIMEOUT et MAX_MCP_OUTPUT_TOKENS règlent la plupart des soucis de démarrage et de sortie.
- Claude Code demande avant d’utiliser les serveurs du .mcp.json d’un projet. Relisez-les comme tout code du dépôt et gardez les tokens dans des références ${VAR}, pas dans le fichier.

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](https://code.claude.com/docs/en/mcp "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](/fr/blog/what-is-mcp-server/ "Qu’est-ce qu’un serveur MCP") ; pour savoir quels serveurs ajouter, voyez [les meilleurs serveurs MCP pour coder](/fr/blog/best-mcp-servers-for-coding/ "Les meilleurs serveurs MCP pour coder").

## Mémo rapide

| Tâche | Commande |
| --- | --- |
| Ajouter un serveur local (stdio) | `claude mcp add <nom> -- <commande> [arguments...]` |
| Ajouter un serveur distant (HTTP) | `claude mcp add --transport http <nom> <url>` |
| Ajouter depuis un extrait JSON | `claude mcp add-json <nom> '<json>'` |
| Partager avec l’équipe | ajouter `--scope project` (écrit `.mcp.json`) |
| Utiliser dans tous vos projets | ajouter `--scope user` |
| Lister les serveurs et leur état | `claude mcp list` |
| Détails d’un serveur | `claude mcp get <nom>` |
| Supprimer un serveur | `claude mcp remove <nom>` |
| Se connecter à un serveur OAuth | `/mcp` dans une session, ou `claude mcp login <nom>` |
| Importer depuis Claude Desktop | `claude mcp add-from-claude-desktop` |
| État, connexion, désactivation, reconnexion | `/mcp` dans Claude Code |

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](/fr/glossary/mcp/ "MCP") rejoint Claude Code de l’une de ces trois façons :

| Transport | Ce que c’est | Quand l’utiliser |
| --- | --- | --- |
| `stdio` | Un processus local que Claude Code lance et avec lequel il dialogue via stdin et stdout | Serveurs lancés avec `npx`, `uvx`, Docker ou votre propre script |
| `http` | Un serveur distant en HTTP streamable | Services hébergés : Notion, Sentry, GitHub, Stripe et d’autres. Anthropic le recommande pour les serveurs distants |
| `sse` | Server-Sent Events | Anciens serveurs distants uniquement. La documentation indique que SSE est déprécié |

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.

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

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

```bash
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 :

| Scope | Option | Stocké dans | Pour qui |
| --- | --- | --- | --- |
| Local (par défaut) | `--scope local` | `~/.claude.json`, sous le chemin de ce projet | Vous seul, dans ce projet seulement |
| Project | `--scope project` | `.mcp.json` à la racine du projet | Tous ceux qui clonent le dépôt |
| User | `--scope user` | `~/.claude.json` | Vous seul, dans tous les projets |

```bash
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 :

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

```bash
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](/fr/blog/claude-code-hooks-guide/ "Guide des hooks Claude Code").

## 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 :

```bash
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 :

```bash
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 :

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

| Symptôme | Que faire |
| --- | --- |
| Le serveur ne se connecte pas | `claude mcp get <nom>` pour l’erreur, puis **Reconnect** dans `/mcp` |
| Un serveur lent expire au démarrage | Lancer avec `MCP_TIMEOUT=10000 claude` (dix secondes) |
| Les appels d’outils longs sont coupés | `MCP_TOOL_TIMEOUT` pour tous les serveurs, ou `"timeout"` par serveur dans `.mcp.json` |
| Avertissement de sortie ou résultats tronqués | Claude Code avertit au-delà de 10 000 tokens et plafonne à 25 000 par défaut. Relever avec `MAX_MCP_OUTPUT_TOKENS=50000` |
| Les options du serveur sont ignorées ou refusées | Options de Claude Code avant le nom, commande du serveur après `--` |
| Avertissement `${VAR}` dans `/mcp` | Définir la variable dans le shell qui lance Claude Code, ou ajouter `:-default` |
| Serveur ignoré au chargement | Le nom est réservé (`workspace`, `claude-in-chrome`, `computer-use` et quelques autres) ; le renommer |
| Le token marche avec curl mais pas ici | Chercher une espace ou un saut de ligne en fin de token collé ; Claude Code signale les espaces cachées |

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](/fr/glossary/prompt-injection/ "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](/fr/blog/ai-coding-agent-security/ "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](/fr/features/mcp-manager/ "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 ?](/fr/blog/what-is-mcp-server/ "Qu’est-ce qu’un serveur MCP")
- [Les meilleurs serveurs MCP pour les agents de code](/fr/blog/best-mcp-servers-for-coding/ "Les meilleurs serveurs MCP pour coder")
- [Gestionnaire MCP](/fr/features/mcp-manager/ "Gestionnaire MCP")
- [L’agent Claude Code](/fr/agents/claude-code/ "Claude Code dans AgentVera")

## Questions fréquentes

**Comment ajouter un serveur MCP à Claude Code ?** Lancez claude mcp add dans le terminal. Pour un serveur local : claude mcp add <nom> -- <commande> [arguments]. Pour un serveur distant : claude mcp add --transport http <nom> <url>. Vérifiez ensuite la connexion avec claude mcp list, ou /mcp dans une session.

**Où Claude Code stocke-t-il les serveurs MCP ?** Les serveurs de scope local (par défaut) et user sont dans ~/.claude.json, les locaux sous le chemin du projet courant. Les serveurs de scope project sont dans un fichier .mcp.json à la racine du projet, que vous pouvez committer pour votre équipe.

**Quelle différence entre les scopes local, project et user ?** Local, c’est vous seul, dans ce projet seulement. Project, c’est tous ceux qui clonent le dépôt, via .mcp.json. User, c’est vous seul, dans tous les projets de votre machine. Si un même nom existe dans plusieurs scopes, local l’emporte sur project, et project sur user.

**Comment se connecter à un serveur MCP qui utilise OAuth ?** Ajoutez-le avec --transport http, puis lancez /mcp dans Claude Code et choisissez Authenticate, ou exécutez claude mcp login <nom> depuis le shell. La connexion dans le navigateur termine le processus, et Claude Code stocke et renouvelle le token.

**Pourquoi mon serveur MCP expire-t-il ou coupe-t-il sa sortie ?** Un serveur lent peut demander plus de temps au démarrage : lancez Claude Code avec MCP_TIMEOUT=10000 pour dix secondes. La sortie des outils est plafonnée à 25 000 tokens par défaut, avec un avertissement au-delà de 10 000 ; relevez le plafond avec MAX_MCP_OUTPUT_TOKENS.

**Un .mcp.json venant d’un dépôt cloné est-il sûr ?** Traitez-le comme tout code que vous n’avez pas écrit. Claude Code demande une approbation avant d’utiliser les serveurs du projet en session interactive, et un dépôt cloné ne peut pas approuver ses propres serveurs. Lisez chaque commande et chaque URL avant d’accepter.

---

**À propos d’AgentVera.** AgentVera est une app de bureau pour macOS, Windows et Linux, développée par Solviera Teknoloji. Elle exécute 18 agents de code IA (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) côte à côte, par projet, dans de vrais terminaux avec les installations et connexions CLI de l’utilisateur. L’offre gratuite inclut des agents illimités. Télécharger: https://agentvera.dev/fr/download/ · Tarifs: https://agentvera.dev/fr/pricing/