Connectez-vous à des outils externes avec MCP

Le Model Context Protocol (MCP) est une norme ouverte pour connecter les agents IA aux outils et sources de données externes. Avec MCP, votre agent peut interroger des bases de données, s'intégrer à des API comme Slack et GitHub, et se connecter à d'autres services sans écrire d'implémentations d'outils personnalisés.

Les serveurs MCP peuvent s'exécuter en tant que processus locaux, se connecter via HTTP ou s'exécuter directement dans votre application SDK.

Démarrage rapide

Cet exemple se connecte au serveur MCP de la documentation Claude Code en utilisant le transport HTTP et utilise allowedTools avec un caractère générique pour autoriser tous les outils du serveur.

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

for await (const message of query({
  prompt: "Use the docs MCP server to explain what hooks are in Claude Code",
  options: {
    mcpServers: {
      "claude-code-docs": {
        type: "http",
        url: "https://code.claude.com/docs/mcp"
      }
    },
    allowedTools: ["mcp__claude-code-docs__*"]
  }
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

L'agent se connecte au serveur de documentation, recherche des informations sur les hooks et retourne les résultats.

Ajouter un serveur MCP

Vous pouvez configurer les serveurs MCP dans le code lors de l'appel de query(), ou dans un fichier .mcp.json que le SDK charge automatiquement.

Dans le code

Passez les serveurs MCP directement dans l'option mcpServers :

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

for await (const message of query({
  prompt: "List files in my project",
  options: {
    mcpServers: {
      "filesystem": {
        command: "npx",
        args: ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/projects"]
      }
    },
    allowedTools: ["mcp__filesystem__*"]
  }
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

À partir d'un fichier de configuration

Créez un fichier .mcp.json à la racine de votre projet. Le SDK le charge automatiquement :

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

Autoriser les outils MCP

Les outils MCP nécessitent une autorisation explicite avant que Claude puisse les utiliser. Sans autorisation, Claude verra que les outils sont disponibles mais ne pourra pas les appeler.

Convention de nommage des outils

Les outils MCP suivent le modèle de nommage mcp__<server-name>__<tool-name>. Par exemple, un serveur GitHub nommé "github" avec un outil list_issues devient mcp__github__list_issues.

Accorder l'accès avec allowedTools

Utilisez allowedTools pour spécifier quels outils MCP Claude peut utiliser :

options: {
  mcpServers: { /* your servers */ },
  allowedTools: [
    "mcp__github__*",              // All tools from the github server
    "mcp__db__query",              // Only the query tool from db server
    "mcp__slack__send_message"     // Only send_message from slack server
  ]
}

Les caractères génériques (*) vous permettent d'autoriser tous les outils d'un serveur sans lister chacun individuellement.

Alternative : Modifier le mode de permission

Au lieu de lister les outils autorisés, vous pouvez modifier le mode de permission pour accorder un accès plus large :

• permissionMode: "acceptEdits" : Approuve automatiquement l'utilisation des outils (demande toujours pour les opérations destructrices)
• permissionMode: "bypassPermissions" : Ignore tous les messages de sécurité, y compris pour les opérations destructrices comme la suppression de fichiers ou l'exécution de commandes shell. À utiliser avec prudence, en particulier en production. Ce mode se propage aux sous-agents générés par l'outil Task.

options: {
  mcpServers: { /* your servers */ },
  permissionMode: "acceptEdits"  // No need for allowedTools
}

Consultez Permissions pour plus de détails sur les modes de permission.

Découvrir les outils disponibles

Pour voir quels outils un serveur MCP fournit, consultez la documentation du serveur ou connectez-vous au serveur et inspectez le message d'initialisation system :

for await (const message of query({ prompt: "...", options })) {
  if (message.type === "system" && message.subtype === "init") {
    console.log("Available MCP tools:", message.mcp_servers);
  }
}

Types de transport

Les serveurs MCP communiquent avec votre agent en utilisant différents protocoles de transport. Consultez la documentation du serveur pour voir quel transport il supporte :

• Si la documentation vous donne une commande à exécuter (comme npx @modelcontextprotocol/server-github), utilisez stdio
• Si la documentation vous donne une URL, utilisez HTTP ou SSE
• Si vous construisez vos propres outils dans le code, utilisez un serveur MCP SDK

Serveurs stdio

Les processus locaux qui communiquent via stdin/stdout. Utilisez ceci pour les serveurs MCP que vous exécutez sur la même machine :

Serveurs HTTP/SSE

Utilisez HTTP ou SSE pour les serveurs MCP hébergés dans le cloud et les API distantes :

Pour HTTP (non-streaming), utilisez "type": "http" à la place.

Serveurs MCP SDK

Définissez des outils personnalisés directement dans le code de votre application au lieu d'exécuter un processus serveur séparé. Consultez le guide des outils personnalisés pour les détails d'implémentation.

Recherche d'outils MCP

Lorsque vous avez de nombreux outils MCP configurés, les définitions d'outils peuvent consommer une portion importante de votre fenêtre de contexte. La recherche d'outils MCP résout ce problème en chargeant les outils dynamiquement à la demande au lieu de les précharger tous.

Comment cela fonctionne

La recherche d'outils s'exécute en mode auto par défaut. Elle s'active lorsque vos descriptions d'outils MCP consommeraient plus de 10 % de la fenêtre de contexte. Lorsqu'elle est déclenchée :

1. Les outils MCP sont marqués avec defer_loading: true plutôt que d'être chargés dans le contexte à l'avance
2. Claude utilise un outil de recherche pour découvrir les outils MCP pertinents si nécessaire
3. Seuls les outils dont Claude a réellement besoin sont chargés dans le contexte

La recherche d'outils nécessite des modèles qui supportent les blocs tool_reference : Sonnet 4 et versions ultérieures, ou Opus 4 et versions ultérieures. Les modèles Haiku ne supportent pas la recherche d'outils.

Configurer la recherche d'outils

Contrôlez le comportement de la recherche d'outils avec la variable d'environnement ENABLE_TOOL_SEARCH :

Définissez la valeur dans l'option env :

const options = {
  mcpServers: { /* your MCP servers */ },
  env: {
    ENABLE_TOOL_SEARCH: "auto:5"  // Enable at 5% threshold
  }
};

Authentification

La plupart des serveurs MCP nécessitent une authentification pour accéder aux services externes. Passez les identifiants via des variables d'environnement dans la configuration du serveur.

Passer les identifiants via des variables d'environnement

Utilisez le champ env pour passer les clés API, les jetons et autres identifiants au serveur MCP :

Consultez Lister les problèmes d'un référentiel pour un exemple complet fonctionnant avec la journalisation de débogage.

En-têtes HTTP pour les serveurs distants

Pour les serveurs HTTP et SSE, passez les en-têtes d'authentification directement dans la configuration du serveur :

Authentification OAuth2

La spécification MCP supporte OAuth 2.1 pour l'autorisation. Le SDK ne gère pas les flux OAuth automatiquement, mais vous pouvez passer les jetons d'accès via les en-têtes après avoir complété le flux OAuth dans votre application :

// After completing OAuth flow in your app
const accessToken = await getAccessTokenFromOAuthFlow();

const options = {
  mcpServers: {
    "oauth-api": {
      type: "http",
      url: "https://api.example.com/mcp",
      headers: {
        Authorization: `Bearer ${accessToken}`
      }
    }
  },
  allowedTools: ["mcp__oauth-api__*"]
};

Exemples

Lister les problèmes d'un référentiel

Cet exemple se connecte au serveur MCP GitHub pour lister les problèmes récents. L'exemple inclut la journalisation de débogage pour vérifier la connexion MCP et les appels d'outils.

Avant d'exécuter, créez un jeton d'accès personnel GitHub avec la portée repo et définissez-le comme variable d'environnement :

export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx

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

for await (const message of query({
  prompt: "List the 3 most recent issues in anthropics/claude-code",
  options: {
    mcpServers: {
      "github": {
        command: "npx",
        args: ["-y", "@modelcontextprotocol/server-github"],
        env: {
          GITHUB_TOKEN: process.env.GITHUB_TOKEN
        }
      }
    },
    allowedTools: ["mcp__github__list_issues"]
  }
})) {
  // Verify MCP server connected successfully
  if (message.type === "system" && message.subtype === "init") {
    console.log("MCP servers:", message.mcp_servers);
  }

  // Log when Claude calls an MCP tool
  if (message.type === "assistant") {
    for (const block of message.content) {
      if (block.type === "tool_use" && block.name.startsWith("mcp__")) {
        console.log("MCP tool called:", block.name);
      }
    }
  }

  // Print the final result
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

Interroger une base de données

Cet exemple utilise le serveur MCP Postgres pour interroger une base de données. La chaîne de connexion est passée comme argument au serveur. L'agent découvre automatiquement le schéma de la base de données, écrit la requête SQL et retourne les résultats :

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

// Connection string from environment variable
const connectionString = process.env.DATABASE_URL;

for await (const message of query({
  // Natural language query - Claude writes the SQL
  prompt: "How many users signed up last week? Break it down by day.",
  options: {
    mcpServers: {
      "postgres": {
        command: "npx",
        // Pass connection string as argument to the server
        args: ["-y", "@modelcontextprotocol/server-postgres", connectionString]
      }
    },
    // Allow only read queries, not writes
    allowedTools: ["mcp__postgres__query"]
  }
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

Gestion des erreurs

Les serveurs MCP peuvent échouer à se connecter pour diverses raisons : le processus serveur pourrait ne pas être installé, les identifiants pourraient être invalides, ou un serveur distant pourrait être inaccessible.

Le SDK émet un message system avec le sous-type init au début de chaque requête. Ce message inclut l'état de la connexion pour chaque serveur MCP. Vérifiez le champ status pour détecter les défaillances de connexion avant que l'agent ne commence à travailler :

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

for await (const message of query({
  prompt: "Process data",
  options: {
    mcpServers: {
      "data-processor": dataServer
    }
  }
})) {
  if (message.type === "system" && message.subtype === "init") {
    const failedServers = message.mcp_servers.filter(
      s => s.status !== "connected"
    );

    if (failedServers.length > 0) {
      console.warn("Failed to connect:", failedServers);
    }
  }

  if (message.type === "result" && message.subtype === "error_during_execution") {
    console.error("Execution failed");
  }
}

Dépannage

Le serveur affiche le statut « failed »

Vérifiez le message init pour voir quels serveurs n'ont pas pu se connecter :

if (message.type === "system" && message.subtype === "init") {
  for (const server of message.mcp_servers) {
    if (server.status === "failed") {
      console.error(`Server ${server.name} failed to connect`);
    }
  }
}

Causes courantes :

• Variables d'environnement manquantes : Assurez-vous que les jetons et identifiants requis sont définis. Pour les serveurs stdio, vérifiez que le champ env correspond à ce que le serveur attend.
• Serveur non installé : Pour les commandes npx, vérifiez que le package existe et que Node.js est dans votre PATH.
• Chaîne de connexion invalide : Pour les serveurs de base de données, vérifiez le format de la chaîne de connexion et que la base de données est accessible.
• Problèmes réseau : Pour les serveurs HTTP/SSE distants, vérifiez que l'URL est accessible et que les pare-feu autorisent la connexion.

Les outils ne sont pas appelés

Si Claude voit les outils mais ne les utilise pas, vérifiez que vous avez accordé la permission avec allowedTools ou en modifiant le mode de permission :

options: {
  mcpServers: { /* your servers */ },
  allowedTools: ["mcp__servername__*"]  // Required for Claude to use the tools
}

Délais d'expiration de la connexion

Le SDK MCP a un délai d'expiration par défaut de 60 secondes pour les connexions serveur. Si votre serveur prend plus de temps pour démarrer, la connexion échouera. Pour les serveurs qui ont besoin de plus de temps de démarrage, envisagez :

• Utiliser un serveur plus léger si disponible
• Préchauffer le serveur avant de démarrer votre agent
• Vérifier les journaux du serveur pour les causes de lenteur d'initialisation

Ressources connexes

• Guide des outils personnalisés : Construisez votre propre serveur MCP qui s'exécute en processus avec votre application SDK
• Permissions : Contrôlez quels outils MCP votre agent peut utiliser avec allowedTools et disallowedTools
• Référence du SDK TypeScript : Référence API complète incluant les options de configuration MCP
• Référence du SDK Python : Référence API complète incluant les options de configuration MCP
• Répertoire des serveurs MCP : Parcourez les serveurs MCP disponibles pour les bases de données, les API et bien d'autres