N-Gage Formation Claude

Claude Code

Brancher un MCP custom dans Claude Code

Statut : stable Plan minimum : Pro Démo : 8-15 min Vérifié le : 2026-05-17

Source officielle : https://code.claude.com/docs/en/mcp

Brancher un MCP custom dans Claude Code

TL;DR

Claude Code peut consommer n'importe quel serveur MCP (Model Context Protocol) déclaré dans deux fichiers : .mcp.json à la racine du projet (versionnable git, partagé avec l'équipe) ou ~/.claude.json global à votre machine (vos serveurs persos). Une fois le serveur déclaré et la session redémarrée, ses outils deviennent appelables directement depuis le CLI, l'IDE ou Claude Desktop, sans dépendre de claude.ai web ni d'un Connector officiel.

Pour qui c'est utile

Pour les profils techniques qui veulent étendre Claude Code au-delà de ses outils natifs et le brancher sur l'écosystème réel de leur stack. Quatre cas typiques :

  • Développeurs backend qui veulent que Claude Code accède à leur base de données locale, leur API privée ou un outil CLI métier sans tout exposer sur Internet.
  • Power users CLI qui orchestrent plusieurs services (GitHub, Sentry, Notion, base SQL, scripts maison) depuis un seul terminal et veulent garder cette orchestration cohérente entre projets.
  • Équipes techniques qui veulent imposer une config MCP partagée à tout le dépôt (mêmes outils, mêmes versions, mêmes scopes) sans dépendre du paramétrage individuel de chaque membre.
  • Auteurs de MCP custom (interne ou open source) qui veulent tester leur serveur en conditions réelles dans Claude Code avant de le publier ou de le déployer.

Comprendre les MCP custom Claude Code (la mécanique sous le capot)

Le sujet est souvent confondu avec les Connectors claude.ai web ou les Extensions Desktop. Trois mécanismes distincts cohabitent.

Le fichier .mcp.json projet se pose à la racine d'un dépôt git. Il est versionnable, partagé entre membres de l'équipe et chargé automatiquement par Claude Code à l'ouverture du projet. C'est le bon endroit pour les serveurs qui font partie du contexte de travail (base SQL locale, MCP maison du produit, outils internes). À la première détection d'un .mcp.json, Claude Code demande une approbation explicite avant de lancer les serveurs : la confiance n'est pas automatique.

Le fichier ~/.claude.json global stocke vos serveurs personnels avec deux scopes possibles : local (visible uniquement dans le projet courant, privé) et user (disponible dans tous vos projets). C'est le bon endroit pour vos credentials persos, vos outils de productivité (Notion, Linear, Todoist) et tout ce qui ne doit pas fuiter dans un dépôt partagé.

Types de transport : stdio pour un binaire ou script local (Claude Code lance la commande et communique via stdin/stdout), http (streamable HTTP) pour un serveur distant exposé en HTTPS, sse historique mais déprécié. Le choix du transport dépend du serveur, pas de votre préférence : la doc du MCP indique lequel utiliser.

Variables d'environnement : .mcp.json accepte la syntaxe ${VAR} ou ${VAR:-default} dans command, args, env, url et headers. C'est le seul mécanisme propre pour committer une config sans exposer les credentials. Les valeurs sont résolues au démarrage de la session depuis l'environnement shell ou un fichier .env chargé en amont.

Différence avec les Connectors web : un Connector côté claude.ai (Notion, Gmail, Linear officiels) est un serveur MCP distant publié par l'éditeur, branché via OAuth dans l'interface claude.ai, et accessible uniquement depuis Claude web ou Desktop. Il ne descend pas dans Claude Code CLI tant qu'il n'est pas redéclaré explicitement.

Différence avec les Extensions Desktop : un fichier .mcpb (Claude Desktop Extension) est un paquet installable d'un clic dans Claude Desktop. Il configure un MCP local sur la machine, mais reste cloisonné à Desktop et n'apparaît pas dans Claude Code CLI sans déclaration équivalente côté ~/.claude.json ou .mcp.json.

À retenir : MCP custom Claude Code et Connector claude.ai web sont deux univers parallèles. Un même serveur peut très bien être branché côté CLI via .mcp.json et côté web via Custom Connector, mais ce sont deux configurations séparées.

Quand brancher un MCP custom vs Connector officiel

Le MCP custom Claude Code s'impose dans ces cas : - Le service est local à votre machine (base SQL, fichiers, scripts maison) - Le serveur MCP est interne à l'entreprise et ne peut pas être exposé publiquement - Vous voulez piloter Claude depuis le terminal ou l'IDE, pas depuis le navigateur - Vous voulez versionner la config MCP avec le code du projet

Le Connector officiel claude.ai est plus pertinent quand : - Le service a un Connector officiel publié par l'éditeur (Notion, Linear, Gmail, GitHub Cloud) - L'authentification OAuth est plus simple que de gérer une clé API en local - L'usage se fait principalement depuis claude.ai web ou Desktop, pas en CLI - Vous voulez éviter d'installer quoi que ce soit en local

Cas mixte fréquent : Notion via Connector officiel pour le travail au quotidien sur claude.ai, et le même MCP Notion redéclaré dans ~/.claude.json user pour pouvoir l'appeler aussi depuis Claude Code en CLI.

Pas à pas détaillé

Créer le fichier .mcp.json du projet

  1. Placez-vous à la racine du dépôt git du projet. Vérifiez qu'aucun .mcp.json n'existe déjà (ls -la .mcp.json).
  2. Lancez claude mcp add --scope project ... pour laisser Claude Code créer le fichier proprement, ou créez-le à la main avec un éditeur de texte.

Déclarer un serveur MCP

  1. Pour un serveur distant HTTP, le plus simple : bash claude mcp add --transport http context7 --scope project https://mcp.context7.com/mcp
  2. Pour un serveur local stdio (script ou binaire sur votre machine) avec credentials : bash claude mcp add --transport stdio --scope project \ --env AIRTABLE_API_KEY=patXXXX airtable \ -- npx -y airtable-mcp-server Tout ce qui suit -- est la commande exacte qui démarre le serveur.
  3. Le fichier .mcp.json ressemble à ceci une fois généré : json { "mcpServers": { "airtable": { "type": "stdio", "command": "npx", "args": ["-y", "airtable-mcp-server"], "env": { "AIRTABLE_API_KEY": "${AIRTABLE_API_KEY}" } } } }
  4. Remplacez les credentials en clair par des ${VAR} et documentez dans le README.md les variables d'environnement attendues.

Redémarrer Claude Code et vérifier

  1. Fermez toutes les sessions Claude Code ouvertes sur le projet, puis relancez claude depuis le terminal à la racine du dépôt.
  2. À la première détection du .mcp.json, Claude Code affiche une demande d'approbation listant les serveurs déclarés. Lisez-la et acceptez si vous reconnaissez les serveurs. Pour réinitialiser ce choix ensuite : claude mcp reset-project-choices.
  3. Tapez /mcp dans la session : la commande affiche l'état de chaque serveur (connecté ou non), le nombre d'outils exposés, et permet de relancer une connexion ou un flow OAuth.
  4. Listez vos serveurs depuis le shell : bash claude mcp list claude mcp get airtable

Mode dev (itération rapide)

  1. Lors du développement d'un MCP maison, relancez claude après chaque modification du serveur pour forcer la reconnexion. Le flag --debug au lancement (claude --debug) affiche les logs de handshake MCP, très utile pour diagnostiquer les transports cassés.
  2. Pour tester rapidement la liste des outils exposés sans lancer une vraie tâche, demandez dans le chat : « Liste les outils du serveur MCP nom-du-serveur ». Claude Code répond avec les noms et descriptions vus côté handshake.

Cas d'usage avec exemples concrets

Brancher GitHub MCP en local : claude mcp add --transport stdio --env GITHUB_TOKEN=ghp_xxxx github --scope user -- npx -y @modelcontextprotocol/server-github. Disponible dans tous vos projets, sans rien committer. Pratique pour piloter issues et PR depuis le CLI.

Brancher un MCP fait maison via mcp-builder : après avoir scaffoldé un serveur Python avec mcp-builder, déclarez-le en stdio dans le .mcp.json du dépôt qui l'utilise : command: "uv", args: ["run", "mon-mcp"]. Le .mcp.json versionné garantit que tout collègue qui clone le repo a la même config.

Brancher une base de données locale : un MCP Postgres pointé sur votre instance Docker locale (postgresql://localhost:5432/dev) permet à Claude Code de lire le schéma, lister les tables, exécuter des requêtes SELECT. À garder en scope local (privé au projet, jamais committé) avec credentials dans ${DATABASE_URL}.

Brancher un service de veille : un MCP custom qui interroge votre flux RSS interne, un dashboard maison ou un endpoint d'observabilité (Sentry, Datadog) via HTTP streamable. Déclaré en --transport http --scope user, il devient appelable dans tous vos projets pour des questions du type « quels sont les nouveaux incidents Sentry de la semaine ».

À retenir

  • .mcp.json à la racine du dépôt = config partagée d'équipe, versionnable git. ~/.claude.json = vos serveurs persos (scopes local et user).
  • Précédence en cas de doublon de nom : local > project > user > plugin > Connector claude.ai. Un même nom dans deux scopes n'est chargé qu'une fois.
  • Trois transports : stdio (binaire local), http (streamable HTTP, distant), sse (déprécié, à éviter pour les nouveaux serveurs).
  • Variables d'environnement supportées partout dans .mcp.json : command, args, env, url, headers. C'est le seul mécanisme propre pour committer une config sans exposer les credentials.
  • À la première détection d'un .mcp.json dans un dépôt, Claude Code demande une approbation explicite avant de lancer les serveurs.
  • MCP custom Claude Code et Connector claude.ai web sont deux configs séparées. Brancher l'un n'active pas l'autre.

Pièges à éviter

  • Chemins absolus vs relatifs : dans command ou args, un chemin relatif est résolu depuis le répertoire de travail du moment, pas depuis la racine du dépôt. Préférez un chemin absolu, un npx qui résout le binaire dans node_modules, ou une variable d'environnement type ${PROJECT_ROOT}/scripts/mon-mcp.
  • Credentials en clair dans le dépôt : ne committez jamais une clé API en dur dans .mcp.json. Utilisez ${VAR} et documentez la variable dans le README.md. Un secret committé reste dans l'historique git même après suppression : tournez immédiatement la clé exposée.
  • JSON invalide : un .mcp.json mal formé empêche Claude Code de charger la config MCP du projet (silencieusement parfois). Validez avec cat .mcp.json | jq . avant chaque commit.
  • Conflits de scope : déclarer le même nom de serveur dans local, project et user ne charge que la version la plus prioritaire (local en tête). Symptôme : vous mettez à jour un serveur côté project mais Claude Code utilise toujours la vieille version local. Utilisez claude mcp list pour voir lequel gagne.
  • Transport mal choisi : un serveur distant déclaré en stdio ou un binaire local déclaré en http ne se connectera jamais. La doc du MCP indique le transport, ne devinez pas.
  • Sécurité prompt injection : un MCP custom qui lit des données externes (mail, web, base de tickets) peut renvoyer du texte contenant des instructions cachées qui détournent Claude. Limitez les scopes, n'exposez à Claude que les outils strictement nécessaires, et relisez les actions sensibles avant validation. Un MCP qui peut écrire (envoyer mail, créer ticket) mérite une revue de sécurité avant de l'ajouter en scope project.
  • Ordre des options de CLI : tous les flags (--transport, --env, --scope, --header) doivent venir AVANT le nom du serveur. Le -- sépare ensuite le nom du serveur de la commande à exécuter.
  • Oublier de redémarrer Claude Code : modifier .mcp.json ou ~/.claude.json sans relancer la session ne prend pas effet. Fermez et rouvrez.

Exercice 1 minute

Dans un dépôt de test, lancez claude mcp add --transport http context7 --scope project https://mcp.context7.com/mcp. Ouvrez le .mcp.json créé à la racine pour visualiser sa structure. Fermez et relancez claude à la racine. Acceptez la demande d'approbation projet, tapez /mcp dans la session et vérifiez que Context7 est connecté et liste ses outils. Posez ensuite une question qui force son usage : « Donne-moi la doc officielle Next.js 15 sur App Router via Context7 ». Si la réponse cite la doc, votre branchement est opérationnel.

Variantes par plan

  • Free : MCP local possible sur Claude Code et Claude Desktop, accès limité aux serveurs distants nécessitant un compte premium côté éditeur.
  • Pro : self-service complet, plusieurs serveurs locaux et distants en parallèle, suffisant pour la majorité des cas individuels.
  • Max : équivalent Pro avec plus de marge sur les limites d'usage Claude Code (qui consomment du contexte additionnel quand un MCP est branché).
  • Team : un .mcp.json versionné dans le dépôt donne la même config MCP à toute l'équipe à chaque clone. Idéal pour standardiser les outils internes.
  • Enterprise : managed configuration poussée par l'admin, validation centralisée des serveurs autorisés, audit des appels MCP, possibilité de bloquer les serveurs non approuvés.

Liens internes