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
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` (processus local) ou `http` (endpoint distant)
Scope	La portée de configuration : `local`, `project` (partagé via `.mcp.json`), `user`

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

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

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).

Placez-vous dans le projet
Fenêtre de terminal
```
cd ~/Projets/lab-claude
```

Créez .mcp.json à la racine

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

Lancez Claude et vérifiez
Fenêtre de terminal
```
claude
```
Dans la session :
```
/mcp
```
La commande liste les serveurs chargés et leur statut. fetch doit apparaître comme connecté.

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.

Ajoutez le serveur au scope user

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

Exportez un token GitHub avec les droits strictement nécessaires
Fenêtre de terminal
```
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.

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.

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)

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.
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 mis dans `.mcp.json`	Déplacer dans `env` du `settings.json` user ou `~/.zshrc`
Serveur qui plante au démarrage	Commande `npx` non résolvable	Vérifier l’installation Node/npm, tester la commande à la main

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

À 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

Prochaines étapes

Claude Code dans VS Code Transposer MCP et les autres briques dans l'éditeur

Briques Claude Code : quand utiliser quoi Revoir l'orientation entre CLAUDE.md, rules, settings, hooks, skills et MCP

Dépannage avancé Claude Code Diagnostiquer un serveur MCP qui ne répond pas ou une permission bloquée