Serveur MCP dans Claude Code : installer et déboguer

Castel Studio, Nice · Publié le 14 octobre 2026

Configurer un serveur MCP, c’est donner à Claude Code accès à ce qui se trouve hors de vos fichiers : un outil de tickets, une base de données, un outil de design, votre propre API. MCP (Model Context Protocol) est un standard ouvert pour ce type de connexions. L’installation elle-même tient en une commande, mais la plupart des problèmes arrivent ensuite : le serveur fonctionne pour vous et pas pour votre équipe, une clé se retrouve dans le dépôt, ou les outils sont listés mais jamais utilisés.

Ce guide suit la documentation officielle MCP de Claude Code. Nous connectons des serveurs MCP à Claude Code tous les jours dans notre studio ; les erreurs listées ci-dessous sont celles que nous voyons le plus souvent chez nos clients.

Avant d’ajouter un serveur : trois questions

Qui en a besoin ? Vous seul, toute l’équipe sur ce projet, ou vous sur tous vos projets. La réponse, c’est le scope, et il détermine où vit la configuration.
Que peut-il toucher ? Un serveur qui se contente de lire un outil de tickets ne présente pas le même risque qu’un serveur capable d’écrire dans votre base de données ou d’envoyer des e-mails. Commencez en lecture seule quand le service le permet.
Où vivent les clés ? Décidez-le avant la première commande. Un jeton tapé dans un fichier partagé est l’erreur la plus difficile à annuler, car il reste dans l’historique du dépôt.

Trois façons d’ajouter un serveur

Un serveur distant en HTTP est le choix habituel pour les services cloud :

claude mcp add --transport http notion https://mcp.notion.com/mcp

Si le service exige un jeton, passez-le en en-tête :

claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

Un serveur local via stdio s’exécute comme un programme sur votre machine :

claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
  -- npx -y airtable-mcp-server

Le -- compte. Tout ce qui le précède est destiné à Claude Code ; tout ce qui le suit est la propre commande du serveur, passée telle quelle.

SSE fonctionne encore, mais il est déprécié. Préférez HTTP quand le service le prend en charge.

Les scopes : qui voit le serveur

Chaque serveur est ajouté avec un scope, et c’est là que les configurations d’équipe dérapent généralement.

Scope	Où il s’applique	Partagé avec l’équipe	Stocké dans
local (par défaut)	ce projet, vous seul	non	`~/.claude.json`
project	ce projet	oui, via le dépôt	`.mcp.json` à la racine du projet
user	tous vos projets	non	`~/.claude.json`

Choisissez-le avec --scope :

claude mcp add --transport http shared-server --scope project https://example.com/mcp

Si le même nom de serveur existe dans plusieurs scopes, le local l’emporte, puis project, puis user. L’entrée gagnante est utilisée en entier ; les champs ne sont pas fusionnés.

Un .mcp.json d’équipe sans secrets

Le scope project écrit un fichier que vous pouvez versionner. Gardez les clés hors de ce fichier avec des variables d’environnement :

{
  "mcpServers": {
    "api-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": { "Authorization": "Bearer ${API_KEY}" }
    }
  }
}

${VAR} est remplacé par la valeur de la variable, et ${VAR:-default} utilise la valeur par défaut en repli. Si une variable n’a ni valeur ni valeur par défaut, Claude Code vous avertit et laisse le texte tel quel : une clé manquante se manifeste donc par un échec de connexion, pas par un silence.

Dans une session interactive, Claude Code demande à chaque personne de valider les serveurs du projet avant la première utilisation. Cette invite est une fonctionnalité : un serveur issu d’un dépôt que vous venez de cloner ne doit pas démarrer sans votre accord.

Vérifier que le MCP server setup fonctionne

claude mcp list
claude mcp get notion

claude mcp list affiche chaque serveur avec un statut : connecté, authentification requise, ou échec de connexion. Dans une session, /mcp affiche la même chose et permet de vous connecter aux serveurs distants qui utilisent OAuth. Pour retirer un serveur, utilisez claude mcp remove notion.

Les problèmes que nous voyons le plus souvent

Le serveur ne fonctionne que pour vous. Il a été ajouté avec le scope local par défaut. Réajoutez-le avec --scope project.
Une clé dans le dépôt. Quelqu’un a collé un jeton dans .mcp.json. Révoquez la clé, puis passez à ${API_KEY}.
Outils listés, jamais autorisés. Les règles de permissions et les sélecteurs de hooks utilisent les noms complets des outils : mcp__server__tool. Un sélecteur mcp__memory seul ne correspond à rien ; consultez notre article sur les hooks de Claude Code.
Réponses énormes. Claude Code vous avertit quand un résultat d’outil dépasse 10 000 tokens et le plafonne à 25 000 par défaut (MAX_MCP_OUTPUT_TOKENS modifie ce plafond). Un outil qui renvoie une table entière à chaque appel a besoin de filtres, pas d’une limite plus haute.
Un serveur que vous n’avez pas vérifié. Les serveurs qui récupèrent du contenu externe peuvent introduire une injection de prompt dans votre session. Ne connectez que des serveurs de confiance, et donnez-leur uniquement les accès nécessaires à la tâche.

Si vous hésitez entre confier une tâche à un serveur MCP, à une skill ou à un subagent, notre guide agents vs skills explique la différence.

Quand nous confier la mise en place

Si votre équipe a besoin de Claude Code connecté à ses propres systèmes, avec une configuration partagée, aucun secret dans le dépôt et des règles qui tiennent, nous installons les serveurs MCP, les agents et des règles testées et vous laissons une configuration fonctionnelle. Vous pouvez voir comment notre propre système est construit sur la page réalisations.

Questions

Pourquoi mes collègues ne voient-ils pas le serveur MCP que j'ai ajouté ?

Parce que le scope par défaut est local : le serveur est enregistré dans votre propre ~/.claude.json, uniquement pour ce projet. Ajoutez-le avec --scope project pour l'écrire dans le .mcp.json du dépôt, que l'équipe peut versionner.

Où placer les clés API d'un serveur MCP ?

Pas dans le .mcp.json lui-même. Écrivez ${API_KEY} dans les champs url, headers, command, args ou env et conservez la valeur dans une variable d'environnement. ${VAR:-default} fournit une valeur de repli.

Pourquoi le serveur apparaît-il dans la liste mais Claude n'utilise jamais ses outils ?

Vérifiez d'abord son statut avec claude mcp list : il peut nécessiter une authentification ou échouer à se connecter. Vérifiez ensuite les noms d'outils dans vos règles de permissions et vos hooks : ils suivent la forme mcp__server__tool.

SSE est-il toujours pris en charge ?

Il fonctionne encore, mais il est déprécié. Utilisez le transport HTTP quand le service le propose ; les versions récentes essaient HTTP en premier et basculent vers SSE automatiquement.