MCP — Connecter Claude Code à des services externes — Claude Code — Le guide pratique

Ce que tu vas apprendre

Ajouter un serveur MCP à ton projet
Interroger GitHub ou une base de données depuis Claude Code
Comprendre la différence entre MCP et Memory
Sécuriser les credentials avec des variables d’environnement

Prérequis

Claude Code v2.1+
Node.js et npm installés
Un token GitHub (pour l’exemple)

MCP (Model Context Protocol) est un pont entre Claude Code et des services externes. Tu poses une question en langage naturel, Claude appelle le serveur MCP, le serveur interroge l’API, et te rend la réponse.

@diagram:flow
Question :: Tu demandes quelque chose en langage naturel.
Claude :: Il appelle le serveur MCP adapté.
Serveur MCP :: Il interroge l'API du service externe.
Réponse :: Le résultat te revient dans la conversation.

Contrairement à Memory qui stocke des données statiques, MCP accède à des données vivantes.

Étapes

1. Ajouter le serveur GitHub MCP

Crée un fichier .mcp.json à la racine de ton projet :

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

Exporte ton token :

export GITHUB_TOKEN="ghp_xxxxxxxxxxxxxxxxxxxx"

Vérifie la connexion :

claude mcp list

Tu dois voir github avec un nombre d’outils > 0.

2. Utiliser les outils MCP

Dans une session Claude Code, tape /mcp puis choisis un serveur. Ou utilise directement :

/mcp__github__list_prs

Exemples de commandes courantes :

Action	Commande
Lister les PRs	`/mcp__github__list_prs`
Voir une PR	`/mcp__github__get_pr 42`
Créer une issue	`/mcp__github__create_issue "Titre" "Description"`
Chercher dans le code	`/mcp__github__search_code "fonction auth"`

3. Configurer plusieurs serveurs

Un fichier .mcp.json peut contenir plusieurs serveurs :

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" }
    },
    "database": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-database"],
      "env": { "DATABASE_URL": "${DATABASE_URL}" }
    },
    "slack": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-slack"],
      "env": { "SLACK_TOKEN": "${SLACK_TOKEN}" }
    }
  }
}

4. Utiliser le transport HTTP

Pour un serveur MCP distant :

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

Avec authentification :

claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer ${API_KEY}"

5. Scoper un MCP à un subagent

Tu peux restreindre un serveur MCP à un subagent spécifique dans son frontmatter :

---
name: db-analyst
description: Analyste de données avec accès base de données
mcpServers:
  database:
    type: http
    url: https://db.internal/mcp
tools: Read, Bash
---

Ce serveur n’est accessible que par ce subagent.

6. Gérer le context bloat

Quand tu connectes beaucoup de serveurs MCP, les descriptions d’outils encombrent le contexte. Deux solutions :

Activer la recherche d’outils (v2.1.84+, Sonnet 4+) :

export ENABLE_TOOL_SEARCH=auto

Forcer le chargement d’un serveur critique :

{
  "mcpServers": {
    "must-have": {
      "command": "node",
      "args": ["./tools/essential.js"],
      "alwaysLoad": true
    }
  }
}

alwaysLoad: true garde les outils toujours disponibles, même avec la recherche active.

Vérification

Fichier .mcp.json créé à la racine
Variables d’environnement exportées
claude mcp list montre le serveur
/mcp affiche les outils disponibles
Une commande MCP retourne des données

Pièges courants

Token hardcodé dans .mcp.json → utilise ${GITHUB_TOKEN} et exporte la variable.
Serveur avec 0 outils → vérifie la connexion et les credentials. Depuis v2.1.128, /mcp signale les serveurs à 0 outils.
.mcp.json commité avec des secrets → ajoute-le à .gitignore si tu mets des URLs internes.
Context bloat → active ENABLE_TOOL_SEARCH=auto si tu as plus de 20 outils MCP.
Serveur qui disparaît après /clear → corrigé en v2.1.136. Mets à jour si besoin.

Récapitulatif

@diagram:cc-mcp

Pour aller plus loin

Inspiré du guide claude-howto de luongnv89 (MIT)