Claude de A à Z

MCP (Model Context Protocol) est le protocole ouvert d'Anthropic qui permet à Claude de se connecter à des serveurs d'outils externes. GitHub, Notion, Slack, une base de données, une API interne : chaque intégration est un serveur MCP que Claude appelle comme il appelle ses outils natifs. Les connecteurs de claude.ai, vus au module 3, reposent sur le même protocole. Ce module couvre le côté terminal : ajouter, partager, déboguer et écrire des serveurs pour Claude Code.

Ce qu'est un serveur MCP

Un serveur MCP est un programme qui expose trois types de choses à Claude :

Le serveur tourne soit en local, lancé par Claude Code et joint par l'entrée-sortie standard (stdio), soit à distance, joint en HTTP. Claude découvre ses outils au démarrage de la session et les voit à côté de Read, Edit ou Bash. Pour comprendre le protocole lui-même, l'article sur MCP, le Model Context Protocol pose les bases.

Ajouter un serveur

Tout passe par la commande claude mcp, hors session :

# Serveur distant (HTTP) — le cas le plus courant aujourd'hui
claude mcp add --transport http github https://api.githubcopilot.com/mcp/
 
# Serveur local lancé par Claude Code (stdio)
claude mcp add postgres -- npx -y @modelcontextprotocol/server-postgres postgresql://localhost/mabase
 
# Avec une variable d'environnement
claude mcp add mon-api --env API_KEY=sk-xxx -- node /chemin/vers/serveur.js
 
# Lister, inspecter, retirer
claude mcp list
claude mcp get github
claude mcp remove github

Le -- sépare les options de Claude Code de la commande du serveur. Oubliez-le et les drapeaux du serveur seront interprétés par claude.

Dans une session, /mcp affiche l'état de chaque serveur, lance l'authentification OAuth pour ceux qui la demandent et permet de se reconnecter.

Les trois portées

L'option --scope décide qui voit le serveur :

Le fichier .mcp.json ressemble à ceci :

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "${DATABASE_URL}"]
    }
  }
}

${DATABASE_URL} est remplacé par la variable d'environnement de chaque développeur. Le fichier se commite sans secret. Par prudence, Claude Code demande une validation la première fois qu'il rencontre les serveurs d'un .mcp.json.

Utiliser un serveur MCP

Une fois configuré, Claude utilise les outils MCP naturellement :

> ouvre un ticket GitHub pour le bug d'authentification qu'on vient de trouver

Claude appelle l'outil de création d'issue du serveur GitHub avec un titre et une description tirés de la conversation.

> cherche dans la base tous les utilisateurs créés cette semaine

Claude écrit la requête SQL, l'exécute via le serveur PostgreSQL et interprète les résultats.

Les ressources se citent avec @, comme un fichier : @github:issue://123. Les prompts d'un serveur apparaissent comme des commandes : /mcp__github__pr_review 456.

Chaque outil MCP coûte du contexte, même inutilisé : son nom et sa description sont chargés. Un serveur qui expose quarante outils dont vous en utilisez deux est un mauvais calcul. /context montre la place qu'ils occupent.

Créer son propre serveur MCP

Pour une API interne ou un outil maison, on écrit son serveur. La formation créer un serveur MCP en Node.js le fait pas à pas ; voici la version minimale.

npm install @modelcontextprotocol/sdk

import { Server } from '@modelcontextprotocol/sdk/server/index.js'
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
import {
  CallToolRequestSchema,
  ListToolsRequestSchema,
} from '@modelcontextprotocol/sdk/types.js'
 
const server = new Server(
  { name: 'mon-api-interne', version: '1.0.0' },
  { capabilities: { tools: {} } }
)
 
// Déclarer les outils disponibles
server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [
    {
      name: 'get_user',
      description: 'Récupère un utilisateur par son ID depuis l\'API interne',
      inputSchema: {
        type: 'object',
        properties: {
          userId: { type: 'string', description: 'ID de l\'utilisateur' },
        },
        required: ['userId'],
      },
    },
  ],
}))
 
// Implémenter les outils
server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const { name, arguments: args } = request.params
 
  if (name === 'get_user') {
    const response = await fetch(`https://api.monapp.fr/users/${args.userId}`, {
      headers: { Authorization: `Bearer ${process.env.API_KEY}` },
    })
    const user = await response.json()
    return {
      content: [{ type: 'text', text: JSON.stringify(user, null, 2) }],
    }
  }
 
  throw new Error(`Outil inconnu : ${name}`)
})
 
const transport = new StdioServerTransport()
await server.connect(transport)

claude mcp add mon-api --env API_KEY=sk-xxx -- node /chemin/vers/mon-serveur-mcp.js

> cherche l'utilisateur 42 et dis-moi depuis quand il est inscrit

La description de chaque outil compte autant que son code : c'est elle que Claude lit pour décider de l'appeler. Écrivez-la comme une consigne, avec le cas d'usage.

Déboguer un serveur

Quand un serveur reste en échec dans /mcp :

# Lancer Claude Code avec les journaux détaillés
claude --debug
 
# Tester le serveur avec l'inspecteur officiel
npx @modelcontextprotocol/inspector node mon-serveur-mcp.js

L'inspecteur ouvre une page web qui liste les outils du serveur et permet de les appeler à la main. Si un outil marche dans l'inspecteur mais pas dans Claude Code, le problème vient de la configuration (chemin, variable manquante), pas du serveur.

Piège classique d'un serveur stdio : un console.log de débogage. La sortie standard sert au protocole, tout texte en trop la corrompt. Écrivez vos traces sur console.error.

Sécurité

Un serveur MCP local tourne avec vos droits. Un serveur distant voit ce que Claude lui envoie. Quatre règles :

• Pas de secret en dur dans .mcp.json : des variables ${VAR}.
• Le moindre privilège : un compte de base en lecture seule si Claude n'a pas à écrire, un jeton GitHub limité aux dépôts utiles.
• Des serveurs d'éditeurs que vous connaissez. Un serveur MCP inconnu, c'est du code d'inconnu.
• Des permissions par outil, que l'on règle comme les autres : mcp__github__create_issue dans allow, mcp__postgres dans deny sur la production. Le module suivant détaille cette syntaxe.

MCP ouvre Claude sur l'ensemble de votre stack. Le module suivant couvre les hooks et settings.json : les permissions, et les commandes qui se déclenchent avant ou après chaque action de Claude.