MCP dans Claude Code : ajouter un serveur (claude mcp add)

Après les concepts de la leçon précédente, passons à la pratique : ajouter un serveur MCP à Claude Code, choisir sa portée, protéger ses secrets et vérifier qu'il répond.

Ajouter un serveur avec claude mcp add

Tout passe par la sous-commande claude mcp, lancée depuis votre terminal (pas dans une session). Deux cas se présentent.

Un serveur distant (HTTP)

C'est le cas des services en ligne qui publient une URL MCP. Le transport recommandé est http :

claude mcp add --transport http mon-service https://mcp.exemple.com/mcp
 
# Avec un en-tête d'authentification fixe
claude mcp add --transport http mon-api https://api.exemple.com/mcp \
  --header "Authorization: Bearer ${MON_API_TOKEN}"

Le transport sse existe encore pour d'anciens serveurs, mais il est déprécié : préférez http quand le service le propose.

Un serveur local (stdio)

Ici, Claude Code lance lui-même un programme sur votre machine. Le double tiret -- sépare les options de Claude Code de la commande du serveur : tout ce qui le suit est transmis tel quel.

claude mcp add tickets --env TICKETS_API_TOKEN=${TICKETS_API_TOKEN} \
  -- npx -y @exemple/serveur-tickets

Oublier ce -- est l'erreur la plus fréquente : les options destinées au serveur sont alors interprétées par Claude Code.

Choisir la portée : local, project ou user

L'option --scope (ou -s) décide où la déclaration est enregistrée et qui en profite :

La portée project convient aux serveurs liés au travail commun (suivi de tickets, documentation interne) : toute l'équipe récupère la même configuration en clonant le dépôt. Par sécurité, Claude Code demande d'approuver un .mcp.json avant d'en lancer les serveurs. La portée user convient aux outils propres à votre façon de travailler.

claude mcp add --scope project --transport http docs-internes https://docs.exemple.com/mcp

Le fichier .mcp.json et les secrets

Avec la portée project, Claude Code écrit un fichier .mcp.json que vous pouvez aussi éditer à la main :

{
  "mcpServers": {
    "tickets": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@exemple/serveur-tickets"],
      "env": {
        "TICKETS_API_TOKEN": "${TICKETS_API_TOKEN}"
      }
    },
    "docs-internes": {
      "type": "http",
      "url": "${DOCS_URL:-https://docs.exemple.com}/mcp"
    }
  }
}

La syntaxe ${VAR} lit une variable d'environnement au lancement, et ${VAR:-défaut} fournit une valeur de repli. C'est ce qui permet de versionner le fichier sans jamais y écrire un secret.

Vérifier et gérer ses serveurs

claude mcp list          # tous les serveurs et leur état
claude mcp get tickets   # le détail d'un serveur
claude mcp remove tickets

claude mcp list affiche un état par serveur : connecté, authentification requise, échec de connexion ou en attente d'approbation (cas d'un .mcp.json de projet pas encore accepté). Dans une session, la commande /mcp montre les mêmes informations, permet d'activer ou de désactiver un serveur et lance la connexion OAuth des serveurs distants qui l'exigent.

Testez ensuite une capacité simple, en langage naturel :

> Utilise le serveur tickets pour lister les cinq derniers tickets ouverts

Si le serveur n'apparaît pas, les causes habituelles sont une variable d'environnement non définie, une commande introuvable ou un -- manquant. Le reste de Claude Code continue de fonctionner pendant votre diagnostic.

Choisir le bon serveur

Avant d'ajouter un serveur, posez-vous trois questions. Répond-il à un besoin réel et récurrent ? Provient-il d'une source de confiance ? Ses permissions sont-elles proportionnées à l'usage prévu ?

Un serveur en lecture seule sur une documentation interne présente peu de risques. Un serveur capable d'écrire dans une base de production en présente beaucoup : limitez sa portée, ou réservez-le à un environnement de test.

Garder le contexte sous contrôle

Un serveur MCP donne accès à des données potentiellement volumineuses. Claude Code avertit au-delà de 10 000 jetons de réponse d'un outil MCP et plafonne par défaut à 25 000 (variable MAX_MCP_OUTPUT_TOKENS pour relever la limite). Rappelez-vous surtout la leçon sur la fenêtre de contexte : mieux vaut « les cinq derniers tickets du module paiement » que « tous les tickets ».

Maintenir ses serveurs

Les serveurs MCP, comme toute dépendance, évoluent. Suivez leurs mises à jour, retirez ceux que vous n'utilisez plus (claude mcp remove) et révisez périodiquement leurs permissions. Un serveur oublié mais toujours connecté est une surface de risque inutile.

En résumé

claude mcp add ajoute un serveur distant (--transport http) ou local (-- commande), --scope choisit entre vous seul, l'équipe (.mcp.json) ou tous vos projets, les secrets passent par ${VAR}, et claude mcp list ou /mcp confirment que tout répond.

La suite du cours aborde les sous-agents, un autre levier de puissance. Explorez aussi les cours et la certification Certified Architect.

Pour aller plus loin : le guide installer, choisir et sécuriser un serveur MCP, valable pour tous les clients MCP, et notre sélection de serveurs MCP vérifiés, avec leur configuration prête à copier.