Guides

MCP dans le SDK

Étendez Claude Code avec des outils personnalisés en utilisant les serveurs Model Context Protocol

Vue d'ensemble

Les serveurs Model Context Protocol (MCP) étendent Claude Code avec des outils et des capacités personnalisés. Les MCP peuvent s'exécuter en tant que processus externes, se connecter via HTTP/SSE, ou s'exécuter directement dans votre application SDK.

Configuration

Configuration de base

Configurez les serveurs MCP dans .mcp.json à la racine de votre projet :

TypeScript

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-filesystem"],
      "env": {
        "ALLOWED_PATHS": "/Users/me/projects"
      }
    }
  }
}

Python

{
  "mcpServers": {
    "filesystem": {
      "command": "python",
      "args": ["-m", "mcp_server_filesystem"],
      "env": {
        "ALLOWED_PATHS": "/Users/me/projects"
      }
    }
  }
}

Utilisation des serveurs MCP dans le SDK

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "Lister les fichiers dans mon projet",
  options: {
    mcpServers: {
      "filesystem": {
        command: "npx",
        args: ["@modelcontextprotocol/server-filesystem"],
        env: {
          ALLOWED_PATHS: "/Users/me/projects"
        }
      }
    },
    allowedTools: ["mcp__filesystem__list_files"]
  }
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

Types de transport

Serveurs stdio

Processus externes communiquant via stdin/stdout :

// Configuration .mcp.json
{
  "mcpServers": {
    "my-tool": {
      "command": "node",
      "args": ["./my-mcp-server.js"],
      "env": {
        "DEBUG": "${DEBUG:-false}"
      }
    }
  }
}

Serveurs HTTP/SSE

Serveurs distants avec communication réseau :

// Configuration serveur SSE
{
  "mcpServers": {
    "remote-api": {
      "type": "sse",
      "url": "https://api.example.com/mcp/sse",
      "headers": {
        "Authorization": "Bearer ${API_TOKEN}"
      }
    }
  }
}

// Configuration serveur HTTP
{
  "mcpServers": {
    "http-service": {
      "type": "http",
      "url": "https://api.example.com/mcp",
      "headers": {
        "X-API-Key": "${API_KEY}"
      }
    }
  }
}

Serveurs MCP SDK

Serveurs en processus s'exécutant dans votre application. Pour des informations détaillées sur la création d'outils personnalisés, consultez le guide des outils personnalisés :

Gestion des ressources

Les serveurs MCP peuvent exposer des ressources que Claude peut lister et lire :

import { query } from "@anthropic-ai/claude-agent-sdk";

// Lister les ressources disponibles
for await (const message of query({
  prompt: "Quelles ressources sont disponibles depuis le serveur de base de données ?",
  options: {
    mcpServers: {
      "database": {
        command: "npx",
        args: ["@modelcontextprotocol/server-database"]
      }
    },
    allowedTools: ["mcp__list_resources", "mcp__read_resource"]
  }
})) {
  if (message.type === "result") console.log(message.result);
}

Authentification

Variables d'environnement

// .mcp.json avec variables d'environnement
{
  "mcpServers": {
    "secure-api": {
      "type": "sse",
      "url": "https://api.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${API_TOKEN}",
        "X-API-Key": "${API_KEY:-default-key}"
      }
    }
  }
}

// Définir les variables d'environnement
process.env.API_TOKEN = "your-token";
process.env.API_KEY = "your-key";

Authentification OAuth2

L'authentification OAuth2 MCP côté client n'est actuellement pas prise en charge.

Gestion des erreurs

Gérez les échecs de connexion MCP avec élégance :

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "Traiter les données",
  options: {
    mcpServers: {
      "data-processor": dataServer
    }
  }
})) {
  if (message.type === "system" && message.subtype === "init") {
    // Vérifier le statut du serveur MCP
    const failedServers = message.mcp_servers.filter(
      s => s.status !== "connected"
    );
    
    if (failedServers.length > 0) {
      console.warn("Échec de connexion :", failedServers);
    }
  }
  
  if (message.type === "result" && message.subtype === "error_during_execution") {
    console.error("Échec de l'exécution");
  }
}

Ressources connexes

Guide des outils personnalisés - Guide détaillé sur la création de serveurs MCP SDK
Référence SDK TypeScript
Référence SDK Python
Permissions SDK
Flux de travail courants