Intermédiaire 12 min

Configurer les serveurs MCP dans Claude Code

Guide complet pour installer, configurer et utiliser les serveurs MCP (Model Context Protocol) avec Claude Code. Connectez vos outils externes directement à Claude.

MCP configuration outils serveurs

MCP, c’est quoi ?

Le Model Context Protocol (MCP) est un protocole ouvert créé par Anthropic qui permet à Claude Code de se connecter à des services externes : bases de données, APIs, outils SaaS, systèmes de fichiers distants. Au lieu de copier-coller des données dans votre prompt, Claude Code interroge directement vos outils via MCP.

Concrètement, MCP transforme Claude Code en hub central. Vous lui dites “crée une page dans Notion avec le récap de ce PR GitHub”, et il le fait en appelant les serveurs MCP Notion et GitHub, sans que vous ayez à quitter votre terminal.

Le protocole est open source, documenté sur modelcontextprotocol.io, et l’écosystème de serveurs grandit rapidement. Il existe des serveurs officiels et communautaires pour la plupart des outils que vous utilisez déjà.

Comment MCP fonctionne dans Claude Code

L’architecture est simple : Claude Code agit comme client MCP. Il se connecte à un ou plusieurs serveurs MCP, chacun exposant des outils (tools) et des ressources (resources).

┌─────────────┐     stdio/SSE     ┌──────────────────┐
│ Claude Code  │ ◄──────────────► │  Serveur MCP     │
│ (client)     │                   │  (ex: Notion)    │
└─────────────┘                   └──────────────────┘
       │            stdio/SSE     ┌──────────────────┐
       └──────────────────────► │  Serveur MCP     │
                                  │  (ex: GitHub)    │
                                  └──────────────────┘

Chaque serveur MCP expose une liste d’outils que Claude Code peut appeler. Par exemple, un serveur Notion expose des outils comme notion-search, notion-create-pages, notion-update-page. Claude Code voit ces outils disponibles et les utilise quand c’est pertinent pour répondre à votre demande.

Deux modes de transport existent :

  • stdio : le serveur est lancé comme un processus local. Claude Code communique avec lui via stdin/stdout. C’est le mode le plus courant et le plus simple.
  • SSE (Server-Sent Events) : le serveur tourne à distance, accessible via HTTP. Utile pour les serveurs partagés en équipe ou hébergés sur un serveur.

Configuration

La configuration MCP se fait via un fichier JSON, à deux niveaux :

  • .mcp.json à la racine du projet : configuration partagée avec l’équipe, versionnée dans Git
  • ~/.claude/mcp.json dans votre home : configuration globale, personnelle, active sur tous vos projets

Structure du fichier

Voici la structure de base d’un .mcp.json :

{
  "mcpServers": {
    "nom-du-serveur": {
      "command": "commande-pour-lancer-le-serveur",
      "args": ["arg1", "arg2"],
      "env": {
        "CLE_API": "votre-cle"
      }
    }
  }
}

Chaque entrée dans mcpServers définit un serveur avec :

  • command : l’exécutable à lancer (souvent npx, node, python, uvx)
  • args : les arguments passés à la commande
  • env : les variables d’environnement (tokens API, clés secrètes)

Exemple concret : un projet avec Notion et GitHub

{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": ["-y", "@notionhq/notion-mcp-server"],
      "env": {
        "OPENAPI_MCP_HEADERS": "{\"Authorization\":\"Bearer ntn_votre_token\",\"Notion-Version\":\"2022-06-28\"}"
      }
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_votre_token"
      }
    }
  }
}

Projet vs global : que mettre où ?

.mcp.json (projet)~/.claude/mcp.json (global)
Serveurs liés au projet (base de données du projet, API métier)Serveurs personnels (calendrier, notes, email)
Tokens partagés avec l’équipe (ou référencés via variables d’env)Vos tokens personnels
Versionné dans GitJamais versionné

Installer des serveurs MCP

Avec la commande claude mcp add

La méthode la plus rapide. Claude Code propose une commande dédiée :

# Ajouter un serveur au projet (écrit dans .mcp.json)
claude mcp add notion -s project -- npx -y @notionhq/notion-mcp-server

# Ajouter un serveur global (écrit dans ~/.claude/mcp.json)
claude mcp add github -s user -- npx -y @modelcontextprotocol/server-github

# Ajouter avec des variables d'environnement
claude mcp add notion -s project \
  -e OPENAPI_MCP_HEADERS='{"Authorization":"Bearer ntn_xxx","Notion-Version":"2022-06-28"}' \
  -- npx -y @notionhq/notion-mcp-server

Les options principales :

  • -s project : scope projet (.mcp.json)
  • -s user : scope global (~/.claude/mcp.json)
  • -e CLE=valeur : variable d’environnement
  • -- : séparateur avant la commande du serveur

Gérer les serveurs

# Lister les serveurs configurés
claude mcp list

# Supprimer un serveur
claude mcp remove notion

# Voir les détails d'un serveur
claude mcp get notion

Configuration manuelle

Vous pouvez aussi éditer directement le fichier .mcp.json. C’est souvent plus pratique pour les configurations complexes ou quand vous copiez une config existante.

Transport SSE

Pour un serveur distant accessible via HTTP :

{
  "mcpServers": {
    "mon-serveur-distant": {
      "type": "sse",
      "url": "https://mcp.exemple.com/sse",
      "headers": {
        "Authorization": "Bearer votre-token"
      }
    }
  }
}

Serveurs MCP populaires

Filesystem

Permet à Claude Code de lire et écrire des fichiers en dehors du répertoire de travail. Utile pour accéder à des configs partagées, des assets, ou d’autres projets.

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y", "@modelcontextprotocol/server-filesystem",
        "/chemin/vers/dossier-autorisé",
        "/autre/dossier"
      ]
    }
  }
}

Les chemins passés en arguments définissent le périmètre autorisé. Le serveur refuse tout accès en dehors de ces dossiers.

GitHub

Accès complet à l’API GitHub : issues, pull requests, repos, fichiers, reviews.

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_votre_token"
      }
    }
  }
}

Exemples d’utilisation une fois configuré :

  • “Liste les issues ouvertes avec le label bug”
  • “Crée une PR avec ces changements”
  • “Résume les commentaires de la PR #42”

Notion

Le serveur officiel Notion donne accès aux bases de données, pages et blocs.

{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": ["-y", "@notionhq/notion-mcp-server"],
      "env": {
        "OPENAPI_MCP_HEADERS": "{\"Authorization\":\"Bearer ntn_votre_token\",\"Notion-Version\":\"2022-06-28\"}"
      }
    }
  }
}

Pour obtenir le token : créez une intégration interne dans notion.so/my-integrations, puis partagez les pages/bases de données concernées avec l’intégration.

Google Calendar

{
  "mcpServers": {
    "google-calendar": {
      "command": "npx",
      "args": ["-y", "@anthropic/claude-google-calendar-mcp"],
      "env": {
        "GOOGLE_CLIENT_ID": "votre-client-id",
        "GOOGLE_CLIENT_SECRET": "votre-client-secret",
        "GOOGLE_REDIRECT_URI": "http://localhost:3000/callback",
        "GOOGLE_REFRESH_TOKEN": "votre-refresh-token"
      }
    }
  }
}

PostgreSQL et bases de données

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "POSTGRES_CONNECTION_STRING": "postgresql://user:password@localhost:5432/mabase"
      }
    }
  }
}

D’autres serveurs de bases de données existent : SQLite, MySQL, MongoDB. La liste complète est sur github.com/modelcontextprotocol/servers.

Autres serveurs notables

  • Puppeteer (@modelcontextprotocol/server-puppeteer) : navigation web, screenshots, scraping
  • Brave Search (@modelcontextprotocol/server-brave-search) : recherche web
  • Slack (@modelcontextprotocol/server-slack) : messages, channels
  • Google Drive (@modelcontextprotocol/server-gdrive) : fichiers Google Drive
  • Memory (@modelcontextprotocol/server-memory) : mémoire persistante entre sessions

Créer un serveur MCP custom

Si aucun serveur existant ne couvre votre besoin, vous pouvez créer le vôtre. Le SDK officiel est disponible en TypeScript et Python.

Exemple minimal en TypeScript

npm install @modelcontextprotocol/sdk
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const server = new McpServer({
  name: "mon-serveur",
  version: "1.0.0",
});

// Déclarer un outil
server.tool(
  "get-status",
  "Récupère le statut du service",
  {
    serviceId: z.string().describe("L'identifiant du service"),
  },
  async ({ serviceId }) => {
    // Votre logique ici
    const status = await fetchServiceStatus(serviceId);
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(status, null, 2),
        },
      ],
    };
  }
);

// Lancer le serveur en mode stdio
const transport = new StdioServerTransport();
await server.connect(transport);

Exemple minimal en Python

pip install mcp
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("mon-serveur")

@mcp.tool()
def get_status(service_id: str) -> str:
    """Récupère le statut du service."""
    status = fetch_service_status(service_id)
    return str(status)

if __name__ == "__main__":
    mcp.run(transport="stdio")

Ensuite, référencez votre serveur dans .mcp.json :

{
  "mcpServers": {
    "mon-serveur": {
      "command": "node",
      "args": ["./mcp-servers/mon-serveur/dist/index.js"]
    }
  }
}

Ou pour la version Python :

{
  "mcpServers": {
    "mon-serveur": {
      "command": "python",
      "args": ["./mcp-servers/mon-serveur/server.py"]
    }
  }
}

Débuguer les serveurs MCP

Les problèmes les plus fréquents et comment les résoudre.

Le serveur ne démarre pas

Vérifiez que la commande fonctionne manuellement dans votre terminal :

# Tester un serveur npx
npx -y @modelcontextprotocol/server-github

# Si ça échoue, c'est un problème d'installation, pas de MCP

Causes fréquentes :

  • Node.js pas installé ou version trop ancienne
  • npx en cache : essayez npx --yes @package/name ou supprimez le cache npx
  • Python pas dans le PATH : utilisez le chemin complet (/usr/bin/python3 ou python3)

Variables d’environnement manquantes

Si un serveur démarre mais que les appels échouent avec des erreurs d’authentification, vérifiez vos tokens :

# Vérifier que la variable est bien définie
claude mcp get notion

Erreurs typiques :

  • Token expiré ou révoqué
  • Mauvais format dans OPENAPI_MCP_HEADERS (le JSON doit être échappé correctement)
  • Permissions insuffisantes sur le token (scopes manquants)

Problèmes de permissions

Certains serveurs nécessitent des permissions spécifiques :

  • Notion : l’intégration doit être partagée avec chaque page/base de données
  • GitHub : le token doit avoir les scopes repo, read:org selon les besoins
  • Filesystem : les chemins doivent exister et être accessibles en lecture/écriture

Voir les logs

Pour diagnostiquer un serveur qui ne répond pas correctement, lancez Claude Code en mode verbose :

claude --verbose

Vous verrez les échanges entre Claude Code et les serveurs MCP, ce qui permet d’identifier précisément où ça bloque.

Vous pouvez aussi utiliser l’inspecteur MCP officiel pour tester un serveur de manière isolée :

npx @modelcontextprotocol/inspector npx -y @modelcontextprotocol/server-github

L’inspecteur ouvre une interface web où vous pouvez lister les outils disponibles et les appeler manuellement.

Bonnes pratiques

Sécurité des tokens

Ne mettez jamais vos tokens en dur dans un .mcp.json versionné. Deux approches :

Option 1 : fichier .mcp.json dans .gitignore

.mcp.json

Simple mais empêche le partage de la config avec l’équipe.

Option 2 : variables d’environnement système

Définissez les tokens dans votre shell profile (~/.bashrc, ~/.zshrc) et référencez-les :

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

Note : la syntaxe ${VAR} pour référencer des variables d’environnement du système dans le fichier .mcp.json n’est pas supportée nativement par tous les serveurs. Préférez la config globale dans ~/.claude/mcp.json pour les tokens personnels.

Scope projet vs global

Règle simple :

  • Projet : tout ce qui est lié au projet (base de données du projet, API métier, serveurs custom)
  • Global : tout ce qui est personnel et transverse (calendrier, notes, email, GitHub si vous l’utilisez partout)

Performance

Chaque serveur MCP est un processus. Quelques conseils :

  • N’activez que les serveurs dont vous avez besoin. 3 à 5 serveurs est un bon maximum pour un usage quotidien.
  • Les serveurs stdio sont plus légers que les serveurs SSE.
  • Si un serveur est lent au démarrage (cas des serveurs npx qui téléchargent le package à chaque fois), installez-le globalement : npm install -g @package/name puis utilisez le chemin direct dans command.

Workflow recommandé

  1. Commencez avec un ou deux serveurs (GitHub + votre outil de gestion de projet)
  2. Testez que tout fonctionne avant d’en ajouter d’autres
  3. Mettez les tokens personnels dans ~/.claude/mcp.json
  4. Partagez la structure (sans les secrets) dans le .mcp.json du projet
  5. Documentez les serveurs utilisés dans votre CLAUDE.md pour que Claude Code sache quand les utiliser
## MCP Servers disponibles

- **notion** : accès aux bases de données du projet (kanban, docs)
- **github** : gestion des issues et PRs
- **postgres** : base de données de production (lecture seule)

Cette documentation dans CLAUDE.md aide Claude Code à choisir le bon outil au bon moment, sans que vous ayez besoin de lui rappeler ce qui est disponible.