Claude Code : brancher un serveur MCP pour étendre Claude vers des outils externes

Claude Code lit très bien votre dépôt, mais il ne voit pas vos issues GitHub, la doc officielle de FastAPI ou une base SQLite locale. Le Model Context Protocol (MCP) permet à Claude de se brancher sur ces ressources externes via des serveurs tiers, sans vous forcer à copier-coller du contexte à la main. Ce guide pose les bases et branche un premier serveur MCP sur lab-claude.

Ce que vous allez apprendre

• Comprendre ce qu'un serveur MCP apporte concrètement à Claude Code
• Ajouter un serveur via claude mcp add ou un fichier .mcp.json partagé
• Choisir le bon scope (local, project, user) selon l'usage
• Choisir le bon transport, et savoir que SSE est déprécié
• S'authentifier sur un serveur distant avec claude mcp login
• Sécuriser l'accès via les permissions settings.json

Dans quel contexte utiliser cette fonctionnalité ?

• Vous voulez qu'une session Claude puisse lire une doc distante sans copier-coller
• Vous travaillez en équipe sur des issues GitHub et voulez les consulter dans la session
• Votre projet utilise une base SQLite ou Postgres locale, et vous voulez des requêtes pilotées
• Vous avez un outil interne déjà doté d'une API MCP

Si aucune de ces situations ne vous concerne, restez sur les briques de base (CLAUDE.md, rules, settings, hooks, skills). MCP est utile quand une ressource utile vit hors du dépôt.

MCP en une page

Un serveur MCP expose des outils (ex : search_repo, fetch_url, run_query) que Claude peut appeler comme n'importe quel autre outil de sa boîte. Côté session, vous ne voyez pas de différence : Claude demande une autorisation, exécute l'outil, récupère un résultat.

Trois notions suffisent pour démarrer :

Notion	Ce que c'est
Serveur MCP	Un processus qui expose des outils (local via stdio, ou distant via HTTP)
Transport	Le canal de communication : stdio pour un processus local, http pour un service distant. sse est déprécié, websocket existe aussi
Scope	La portée de configuration : local, project (partagé via .mcp.json), user

Glissez pour voir

Prérequis

• Projet lab-claude opérationnel
• Conventions posées (voir configurer CLAUDE.md)
• settings.json avec au minimum un socle de permissions (voir settings.json avancé)

Les 3 scopes d'un serveur MCP

Claude Code charge les serveurs MCP depuis plusieurs emplacements, du plus local au plus global :

Scope	Emplacement	Usage	Partagé via git
local	Config locale de la CLI	Serveurs testés sur votre machine uniquement	Non
project	.mcp.json à la racine du dépôt	Serveurs partagés avec l'équipe	Oui
user	Configuration utilisateur globale	Serveurs disponibles sur tous vos projets	Non

Glissez pour voir

Règle simple : local pour expérimenter, project pour engager l'équipe, user pour ce qui vous suit partout (ex : GitHub).

Priorité en cas de conflit

Si deux définitions portent le même nom de serveur, la précédence complète est : local, puis project, puis user, puis les serveurs fournis par un plugin, puis les connecteurs claude.ai. Un test local peut donc temporairement supplanter un serveur d'équipe, ce qui est pratique en diagnostic, et dangereux si on l'oublie.

Ajouter un serveur : claude mcp add ou .mcp.json

Deux chemins, au même résultat.

Voie rapide (interactive) :

claude mcp add <nom> -- <commande> [args...]

Exemple :

claude mcp add fetch -- npx -y @modelcontextprotocol/server-fetch

Voie partagée (versionnée) : créez .mcp.json à la racine du dépôt :

{
  "mcpServers": {
    "fetch": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-fetch"]
    }
  }
}

Le fichier .mcp.json est lu automatiquement au démarrage de la CLI depuis la racine du projet. Committez-le quand le serveur concerne toute l'équipe.

Exemple 1 : serveur fetch sur lab-claude

Objectif : permettre à Claude de consulter une URL de documentation distante pendant une session (par exemple la doc officielle de FastAPI).

1. Placez-vous dans le projet

   cd ~/Projets/lab-claude

2. Créez .mcp.json à la racine

   {
     "mcpServers": {
       "fetch": {
         "command": "npx",
         "args": ["-y", "@modelcontextprotocol/server-fetch"]
       }
     }
   }

3. Lancez Claude et vérifiez

   claude

   Dans la session :

   /mcp

   La commande liste les serveurs chargés et leur statut. fetch doit apparaître comme connecté.

4. Testez l'usage réel

   Utilise fetch pour récupérer https://fastapi.tiangolo.com/tutorial/path-params/
   et résume en 5 points les règles de path parameters.
   Ne modifie aucun fichier.

Claude appelle le serveur fetch, récupère la page, et répond sans que vous ayez collé de contenu.

Exemple 2 : serveur github au niveau user

Objectif : consulter les issues et PRs de vos dépôts GitHub depuis n'importe quelle session, pas seulement lab-claude.

1. Ajoutez le serveur au scope user

   claude mcp add --scope user github -- npx -y @modelcontextprotocol/server-github

2. Exportez un token GitHub avec les droits strictement nécessaires

   export GITHUB_PERSONAL_ACCESS_TOKEN=ghp_xxx

   Pour rendre la variable persistante, posez-la dans votre shell (~/.zshrc) ou mieux, dans env du settings.json user si vous acceptez de la lier à Claude.

3. Testez depuis une session

   /mcp

   Puis :

   Liste les 5 dernières issues ouvertes de stephanerobert/lab-claude.
   Résume en 3 points les thèmes récurrents.
   Ne modifie aucun fichier.

Jamais de secrets dans `.mcp.json`

.mcp.json est commité. N'y mettez jamais de token ni de clé API. Les secrets passent par variables d'environnement (env dans settings.json, ~/.zshrc, ou un gestionnaire dédié).

Quel transport choisir pour un serveur distant ?

Prenez HTTP. C'est la réponse par défaut, et la documentation l'énonce directement : « The SSE (Server-Sent Events) transport is deprecated. Use HTTP servers instead, where available. »

Transport	Statut	Usage
stdio	courant	un processus local que Claude Code lance lui-même
http	recommandé	un service distant
sse	déprécié	héritage, à migrer
websocket	disponible	cas particuliers

Glissez pour voir

Que faire d'un service qui n'expose encore que du SSE ? Rien de spécial : ajoutez-le comme un serveur HTTP. Claude Code essaie HTTP d'abord et bascule sur SSE quand le serveur ne l'accepte pas. La bascule automatique demande Claude Code 2.1.265 ou plus récent.

claude mcp add --transport http mon-service https://exemple.fr/mcp

Autrement dit, vous n'avez plus à écrire --transport sse : la même commande couvre les deux cas, et votre configuration ne changera pas le jour où le service migrera.

Tool Search : pourquoi « beaucoup de serveurs » ne sature plus le contexte

Un raisonnement répandu est devenu faux. On lisait, à juste titre il y a quelques mois, que brancher de nombreux serveurs MCP saturait la fenêtre de contexte dès le démarrage, parce que la définition complète de chaque outil y était injectée.

Claude Code emploie désormais Tool Search, et c'est le comportement par défaut. Les définitions complètes sont différées jusqu'au moment où Claude en a besoin : il peut chercher un outil puis l'appeler, sans attendre que tous les serveurs se soient connectés au démarrage. Un serveur qui finit de se connecter pendant que Claude travaille voit ses noms d'outils listés dès la requête suivante, dans le même tour.

Conséquence pratique : brancher plusieurs serveurs coûte beaucoup moins qu'avant en contexte et en latence de démarrage. Le critère de sélection redevient l'utilité, pas la peur de la saturation.

Trois configurations sans Tool Search

Le mécanisme n'est pas actif partout. Il ne l'est pas quand vous employez un ANTHROPIC_BASE_URL personnalisé, quand ENABLE_TOOL_SEARCH=false est posé, et sur des modèles antérieurs à la génération 4.5 sur Google Cloud Agent Platform.

Dans ces cas, l'ancien raisonnement reste valable : chaque serveur branché pèse sur le contexte dès le départ. C'est une raison de vérifier avant de multiplier les serveurs sur une configuration d'entreprise.

S'authentifier sur un serveur distant

Beaucoup de serveurs distants demandent une authentification, et le flux passe par OAuth. Depuis Claude Code 2.1.186, il se déclenche directement depuis le shell, sans passer par le panneau /mcp d'une session :

claude mcp login mon-service

Trois comportements utiles à connaître. Le jeton est stocké de façon sécurisée et rafraîchi automatiquement : quand un appel d'outil renvoie un 401, Claude Code rafraîchit le jeton et retente une fois. Depuis la 2.1.191, la commande détecte l'absence de navigateur local, cas d'une session SSH ou d'un Linux sans serveur d'affichage, et imprime l'URL d'autorisation au lieu d'essayer d'ouvrir un navigateur. Enfin, l'entrée « Clear authentication » du menu /mcp révoque l'accès.

Pour un schéma qui n'est pas OAuth, par exemple Kerberos, un jeton à durée de vie courte ou un SSO interne, le champ headersHelper désigne un programme qui produit les en-têtes à chaque appel :

{
  "mcpServers": {
    "api-interne": {
      "type": "http",
      "url": "https://mcp.interne.exemple.fr",
      "headersHelper": "/opt/bin/entetes-mcp.sh"
    }
  }
}

C'est la bonne réponse au problème du secret dans le fichier de configuration : le jeton n'est jamais écrit, il est produit au moment de l'appel.

Permissions MCP dans settings.json

Les outils exposés par un serveur MCP sont nommés mcp__<serveur>__<outil>. Vous pouvez les pré-autoriser, les refuser ou les soumettre à confirmation, exactement comme Bash ou Read.

Exemple dans .claude/settings.json :

{
  "permissions": {
    "allow": [
      "mcp__fetch__fetch"
    ],
    "ask": [
      "mcp__github__create_issue",
      "mcp__github__create_pull_request"
    ],
    "deny": [
      "mcp__github__delete_repository"
    ]
  }
}

Règles à garder :

• allow sur les actions en lecture seule (fetch, list_issues, read_file)
• ask sur les actions qui engagent quelqu'un (create_issue, comment, create_pull_request)
• deny sur tout ce qui est destructif ou irréversible

Détails sur la syntaxe des permissions dans settings.json avancé.

Où MCP s'insère dans la boîte à outils Claude Code

MCP ne remplace aucune brique existante : il étend la portée de Claude vers l'extérieur.

Brique	Rôle
CLAUDE.md, rules	Faits et règles du projet
settings.json	Permissions des outils (y compris MCP)
hooks	Automatisation sur événements
skills	Procédures invocables
MCP	Outils supplémentaires (ressources hors dépôt)

Glissez pour voir

Règle d'orientation : si la ressource est dans le dépôt, pas besoin de MCP. Dès qu'elle vit ailleurs (doc distante, issues, base externe), un serveur MCP devient pertinent.

Vue d'ensemble dans briques Claude Code : quand utiliser quoi.

Bonnes pratiques sur lab-claude

• Commencer petit : un serveur MCP utile vaut mieux que trois serveurs que personne n'utilise. Le motif n'est plus la saturation du contexte, que Tool Search a levée, mais la surface d'outils que vous acceptez d'exposer.
• Scoper correctement : .mcp.json seulement pour ce qui concerne le projet, user pour ce qui vous suit.
• Valider les outils exposés : /mcp montre la liste, examinez-la avant de faire confiance.
• Autoriser finement : jamais de mcp__* en wildcard dans allow, toujours par outil nommé.
• Surveiller les coûts : un serveur fetch sur un gros document consomme beaucoup de tokens, utilisez /cost régulièrement.

Erreurs fréquentes

Symptôme	Cause probable	Correction
/mcp ne liste pas le serveur	.mcp.json invalide ou mauvais chemin	Valider le JSON, relancer la CLI depuis la racine
Serveur connecté mais outils non appelés	Description trop vague côté serveur	Reformuler le prompt pour nommer explicitement le serveur
Prompt de permission à chaque appel	Outil non listé dans allow	Ajouter mcp__<serveur>__<outil> dans settings.json
Token API qui fuit dans git	secret écrit dans .mcp.json	le sortir vers env du settings.json user, ou mieux, produire l'en-tête à la demande avec headersHelper
401 répété sur un serveur distant	jeton OAuth expiré et non renouvelable	relancer claude mcp login <nom> ; en SSH, la commande imprime l'URL au lieu d'ouvrir un navigateur
Un serveur d'équipe se comporte autrement chez vous	un serveur local du même nom le supplante	la précédence va local, project, user, plugin, connecteur : vérifiez avec /mcp
Serveur qui plante au démarrage	Commande npx non résolvable	Vérifier l'installation Node/npm, tester la commande à la main

Glissez pour voir

Checklist de fin de guide

• J'ai choisi le bon scope pour mon serveur MCP (local, project, user)
• .mcp.json est à la racine et ne contient aucun secret
• /mcp liste mon serveur comme connecté
• J'ai autorisé finement les outils MCP dans settings.json
• Les actions qui engagent sont en ask, les destructives en deny
• J'ai testé au moins un appel d'outil avec un prompt réel

Contrôle de connaissances

Vérifiez que l'essentiel de ce guide est acquis. Les questions portent uniquement sur ce qui vient d'être expliqué ici.

Contrôle de connaissances

Validez vos connaissances avec ce quiz interactif

6 questions

6 min.

70% requis

Informations

• Le chronomètre démarre au clic sur Démarrer
• Questions à choix multiples, vrai/faux et réponses courtes
• Vous pouvez naviguer entre les questions
• Les résultats détaillés sont affichés à la fin

Démarrer le quiz

Lance le quiz et démarre le chronomètre

À retenir

• MCP étend Claude vers des ressources hors du dépôt, il ne remplace aucune brique
• Trois scopes : local pour tester, project pour partager, user pour ce qui vous suit
• .mcp.json se commite, les secrets restent dans l'environnement
• Les permissions MCP vivent dans settings.json, jamais en wildcard
• Un serveur utile, bien scopé et bien autorisé, vaut mieux que dix serveurs ignorés

Pour aller plus loin

• Mode headless et intégration CI : Les serveurs MCP en environnement non interactif, avec les permissions que cela impose.
• Claude Code dans VS Code : Les mêmes serveurs pilotés depuis l'éditeur, panneau et checkpoints à l'appui.
• Dépannage avancé : permissions, config, diff : Le diagnostic d'un serveur MCP muet ou d'un outil bloqué par une permission.

×

📖 Voir la documentation →