Protocole MCP avancé : transports et architecture

Au-delà des bases

Vous savez créer un MCP, installer des tools et les utiliser dans Claude Code. Cette page va plus loin : le protocole JSON-RPC sous-jacent, les différents transports disponibles, la négociation de capabilities et les techniques de debugging avancé.

Spécification JSON-RPC 2.0

Le MCP repose sur JSON-RPC 2.0, un protocole léger de communication par messages JSON. Chaque échange suit un format strict : requête, réponse, ou notification.

Format d'une requête

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get-weather",
    "arguments": { "city": "Paris" }
  }
}

• jsonrpc : toujours "2.0"
• id : identifiant unique pour corréler la réponse
• method : la méthode appelée
• params : les paramètres de l'appel

Format d'une réponse

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Météo à Paris : 18°C, Nuageux"
      }
    ]
  }
}

Les principales méthodes MCP

Capabilities negotiation

Au démarrage, Claude Code et le MCP Server échangent leurs capabilities. C'est la première interaction après la connexion.

Requête d'initialisation

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {
      "sampling": {}
    },
    "clientInfo": {
      "name": "claude-code",
      "version": "1.0.0"
    }
  }
}

Réponse du serveur

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2024-11-05",
    "capabilities": {
      "tools": {},
      "resources": { "subscribe": true },
      "prompts": {}
    },
    "serverInfo": {
      "name": "mcp-weather",
      "version": "1.0.0"
    }
  }
}

Le client et le serveur s'accordent sur la version du protocole et annoncent ce qu'ils supportent. Un serveur qui ne déclare pas tools dans ses capabilities ne recevra pas d'appels tools/call.

Capabilities disponibles

Transport stdio : le mode par défaut

Le transport stdio (standard input/output) est le plus simple et le plus courant. Claude Code lance le processus MCP Server et communique via les flux stdin/stdout du processus.

Fonctionnement

Claude Code                      MCP Server (processus fils)
     |                                    |
     |--- stdin: requête JSON-RPC ------->|
     |                                    |--- traitement
     |<--- stdout: réponse JSON-RPC ------|
     |                                    |
     |--- stdin: notification ----------->|

Chaque message est une ligne JSON terminée par \n. Les logs du serveur passent par stderr pour ne pas interférer avec le protocole.

Configuration

{
  "mcpServers": {
    "my-mcp": {
      "command": "node",
      "args": ["dist/index.js"],
      "env": { "API_KEY": "..." }
    }
  }
}

Avantages et limites

• Simple : pas de réseau, pas de ports, pas de configuration serveur
• Sécurisé : la communication est locale, pas de surface d'attaque réseau
• Limité : un processus par connexion, pas de partage entre plusieurs clients
• Local : le MCP doit tourner sur la même machine que Claude Code

Transport SSE : Server-Sent Events

Le transport SSE permet de connecter Claude Code à un MCP Server distant via HTTP. Le client envoie des requêtes POST et reçoit les réponses via un flux SSE (Server-Sent Events).

Quand l'utiliser

• Le MCP Server tourne sur un serveur distant (cloud, VPS, réseau interne)
• Plusieurs clients doivent se connecter au même MCP Server
• Vous voulez un MCP Server toujours disponible, sans le relancer à chaque session

Configuration

{
  "mcpServers": {
    "remote-db": {
      "url": "https://mcp.example.com/sse",
      "headers": {
        "Authorization": "Bearer votre-token"
      }
    }
  }
}

Flux de communication

Claude Code                           MCP Server (HTTP)
     |                                       |
     |--- GET /sse (établir le flux SSE) --->|
     |<--- SSE: endpoint URL ----------------|
     |                                       |
     |--- POST /messages (requête) --------->|
     |<--- SSE: réponse JSON-RPC ------------|

Transport Streamable HTTP : le nouveau standard

Le transport Streamable HTTP est le successeur du SSE pour les MCP distants. Il combine la simplicité du HTTP avec le streaming bidirectionnel.

Différences avec SSE

Configuration

{
  "mcpServers": {
    "remote-api": {
      "url": "https://mcp.example.com/mcp",
      "headers": {
        "Authorization": "Bearer votre-token"
      }
    }
  }
}

Sampling : quand le MCP demande au LLM

Le sampling est une capability spéciale : elle permet au MCP Server de demander à Claude de compléter un prompt. C'est un flux inversé où le serveur devient temporairement "client" du LLM.

Cas d'usage

• Un tool de traduction qui demande à Claude de traduire un texte
• Un tool d'analyse qui demande à Claude de résumer des données
• Un outil de génération qui utilise Claude pour produire du contenu

Flux de communication

Claude Code        MCP Server               Claude (LLM)
     |                  |                         |
     |-- tools/call --->|                         |
     |                  |--- sampling/request ---->|
     |                  |<--- réponse LLM ---------|
     |<-- résultat -----|                         |

Performance et latence

Les MCP ajoutent de la latence à chaque interaction. Voici les sources principales et comment les optimiser.

Sources de latence

Gestion des timeouts

Claude Code impose un timeout par défaut sur les appels MCP. Si votre tool fait des opérations longues :

// Dans votre tool handler, envoyez des notifications de progression
server.tool(
  "long-operation",
  "Opération qui prend du temps",
  { input: z.string() },
  async ({ input }, { sendProgress }) => {
    await sendProgress(0, 100, "Démarrage...");
    // ... opération longue
    await sendProgress(50, 100, "Traitement en cours...");
    // ... suite
    await sendProgress(100, 100, "Terminé");

    return {
      content: [{ type: "text" as const, text: "Résultat de l'opération" }],
    };
  }
);

Sécurité avancée

Sandboxing

Chaque MCP Server tourne dans son propre processus. Mais il a accès au système de fichiers et au réseau de la machine hôte. Pour limiter les risques :

• Exécutez les MCP dans un conteneur Docker avec des volumes restreints
• Utilisez des tokens avec scopes minimaux (lecture seule quand possible)
• Appliquez des règles réseau pour limiter les connexions sortantes

Audit logs

Pour tracer ce que fait un MCP :

// Wrapper de logging pour tous les appels de tools
server.tool("my-tool", "Description", { param: z.string() }, async ({ param }) => {
  console.error(`[AUDIT] tool=my-tool param=${param} time=${new Date().toISOString()}`);
  // ... logique du tool
  const result = "...";
  console.error(`[AUDIT] tool=my-tool result_length=${result.length}`);
  return { content: [{ type: "text" as const, text: result }] };
});

Les logs sur stderr ne perturbent pas le protocole et peuvent être capturés par votre système de monitoring.

Token rotation

Pour les MCP qui utilisent des tokens d'API externe :

• Stockez les tokens dans des variables d'environnement, pas dans le code
• Mettez en place une rotation régulière des tokens (tous les 90 jours minimum)
• Utilisez un gestionnaire de secrets (Vault, AWS Secrets Manager) pour la production
• Révoquez immédiatement tout token potentiellement compromis

Debugging : diagnostiquer les problèmes

Inspection JSON-RPC

L'inspecteur MCP est votre meilleur outil pour débugger :

# Inspecter un serveur stdio
npx @modelcontextprotocol/inspector node dist/index.js

# Inspecter un serveur SSE
npx @modelcontextprotocol/inspector --url https://mcp.example.com/sse

L'inspecteur affiche chaque message JSON-RPC échangé, ce qui permet de voir exactement ce que le serveur reçoit et retourne.

Logging verbeux côté Claude Code

# Lancer Claude Code avec les logs MCP détaillés
claude --verbose

Le flag --verbose affiche les échanges JSON-RPC avec chaque MCP dans le terminal.

Vérifier la santé d'un MCP

# Lister les MCP configurés et leur statut
claude mcp list

Si un MCP apparaît comme "disconnected" ou "error" :

# Exemple pour un MCP Node.js
node /chemin/vers/mcp/dist/index.js

npx @modelcontextprotocol/inspector node /chemin/vers/mcp/dist/index.js

Erreurs fréquentes en debug

Prochaines étapes

• Créer un MCP Server en TypeScript : tutoriel complet avec le SDK TypeScript
• Créer un MCP Server en Python : tutoriel avec le SDK Python et les décorateurs
• Sécurité des MCP : guide complet de sécurisation
• Comprendre les MCP : revenir aux fondamentaux du protocole