Connecteur MCP

La fonctionnalité de connecteur Model Context Protocol (MCP) de Claude vous permet de vous connecter à des serveurs MCP distants directement depuis l'API Messages sans client MCP séparé.

Fonctionnalités principales

• Intégration directe à l'API : Connectez-vous aux serveurs MCP sans implémenter un client MCP
• Prise en charge des appels d'outils : Accédez aux outils MCP via l'API Messages
• Configuration flexible des outils : Activez tous les outils, autorisez des outils spécifiques ou bloquez les outils indésirables
• Configuration par outil : Configurez des outils individuels avec des paramètres personnalisés
• Authentification OAuth : Prise en charge des jetons OAuth Bearer pour les serveurs authentifiés
• Plusieurs serveurs : Connectez-vous à plusieurs serveurs MCP dans une seule requête

Limitations

• Parmi l'ensemble des fonctionnalités de la spécification MCP, seuls les appels d'outils sont actuellement pris en charge.
• Le serveur doit être exposé publiquement via HTTP (prend en charge les transports Streamable HTTP et SSE). Les serveurs STDIO locaux ne peuvent pas être connectés directement.
• Le connecteur MCP n'est actuellement pas pris en charge sur Amazon Bedrock et Google Vertex.

Utilisation du connecteur MCP dans l'API Messages

Le connecteur MCP utilise deux composants :

1. Définition du serveur MCP (tableau mcp_servers) : Définit les détails de connexion au serveur (URL, authentification)
2. Ensemble d'outils MCP (tableau tools) : Configure les outils à activer et comment les configurer

Exemple de base

Cet exemple active tous les outils d'un serveur MCP avec la configuration par défaut :

curl https://api.anthropic.com/v1/messages \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: mcp-client-2025-11-20" \
  -d '{
    "model": "claude-opus-4-6",
    "max_tokens": 1000,
    "messages": [{"role": "user", "content": "What tools do you have available?"}],
    "mcp_servers": [
      {
        "type": "url",
        "url": "https://example-server.modelcontextprotocol.io/sse",
        "name": "example-mcp",
        "authorization_token": "YOUR_TOKEN"
      }
    ],
    "tools": [
      {
        "type": "mcp_toolset",
        "mcp_server_name": "example-mcp"
      }
    ]
  }'

Configuration du serveur MCP

Chaque serveur MCP dans le tableau mcp_servers définit les détails de connexion :

{
  "type": "url",
  "url": "https://example-server.modelcontextprotocol.io/sse",
  "name": "example-mcp",
  "authorization_token": "YOUR_TOKEN"
}

Descriptions des champs

Configuration de l'ensemble d'outils MCP

Le MCPToolset se trouve dans le tableau tools et configure les outils du serveur MCP qui sont activés et comment ils doivent être configurés.

Structure de base

{
  "type": "mcp_toolset",
  "mcp_server_name": "example-mcp",
  "default_config": {
    "enabled": true,
    "defer_loading": false
  },
  "configs": {
    "specific_tool_name": {
      "enabled": true,
      "defer_loading": true
    }
  }
}

Descriptions des champs

Options de configuration des outils

Chaque outil (qu'il soit configuré dans default_config ou dans configs) prend en charge les champs suivants :

Fusion des configurations

Les valeurs de configuration fusionnent avec cette priorité (de la plus haute à la plus basse) :

1. Paramètres spécifiques à l'outil dans configs
2. default_config au niveau de l'ensemble
3. Valeurs par défaut du système

Exemple :

{
  "type": "mcp_toolset",
  "mcp_server_name": "google-calendar-mcp",
  "default_config": {
    "defer_loading": true
  },
  "configs": {
    "search_events": {
      "enabled": false
    }
  }
}

Résultat :

• search_events : enabled: false (depuis configs), defer_loading: true (depuis default_config)
• Tous les autres outils : enabled: true (valeur par défaut du système), defer_loading: true (depuis default_config)

Modèles de configuration courants

Activer tous les outils avec la configuration par défaut

Le modèle le plus simple - activer tous les outils d'un serveur :

{
  "type": "mcp_toolset",
  "mcp_server_name": "google-calendar-mcp"
}

Liste d'autorisation - Activer uniquement des outils spécifiques

Définissez enabled: false comme valeur par défaut, puis activez explicitement des outils spécifiques :

{
  "type": "mcp_toolset",
  "mcp_server_name": "google-calendar-mcp",
  "default_config": {
    "enabled": false
  },
  "configs": {
    "search_events": {
      "enabled": true
    },
    "create_event": {
      "enabled": true
    }
  }
}

Liste de blocage - Désactiver des outils spécifiques

Activez tous les outils par défaut, puis désactivez explicitement les outils indésirables :

{
  "type": "mcp_toolset",
  "mcp_server_name": "google-calendar-mcp",
  "configs": {
    "delete_all_events": {
      "enabled": false
    },
    "share_calendar_publicly": {
      "enabled": false
    }
  }
}

Mixte - Liste d'autorisation avec configuration par outil

Combinez la liste d'autorisation avec une configuration personnalisée pour chaque outil :

{
  "type": "mcp_toolset",
  "mcp_server_name": "google-calendar-mcp",
  "default_config": {
    "enabled": false,
    "defer_loading": true
  },
  "configs": {
    "search_events": {
      "enabled": true,
      "defer_loading": false
    },
    "list_events": {
      "enabled": true
    }
  }
}

Dans cet exemple :

• search_events est activé avec defer_loading: false
• list_events est activé avec defer_loading: true (hérité de default_config)
• Tous les autres outils sont désactivés

Règles de validation

L'API applique ces règles de validation :

• Le serveur doit exister : Le mcp_server_name dans un MCPToolset doit correspondre à un serveur défini dans le tableau mcp_servers
• Le serveur doit être utilisé : Chaque serveur MCP défini dans mcp_servers doit être référencé par exactement un MCPToolset
• Ensemble d'outils unique par serveur : Chaque serveur MCP ne peut être référencé que par un seul MCPToolset
• Noms d'outils inconnus : Si un nom d'outil dans configs n'existe pas sur le serveur MCP, un avertissement backend est enregistré mais aucune erreur n'est retournée (les serveurs MCP peuvent avoir une disponibilité d'outils dynamique)

Types de contenu de réponse

Lorsque Claude utilise des outils MCP, la réponse inclura deux nouveaux types de blocs de contenu :

Bloc d'utilisation d'outil MCP

{
  "type": "mcp_tool_use",
  "id": "mcptoolu_014Q35RayjACSWkSj4X2yov1",
  "name": "echo",
  "server_name": "example-mcp",
  "input": { "param1": "value1", "param2": "value2" }
}

Bloc de résultat d'outil MCP

{
  "type": "mcp_tool_result",
  "tool_use_id": "mcptoolu_014Q35RayjACSWkSj4X2yov1",
  "is_error": false,
  "content": [
    {
      "type": "text",
      "text": "Hello"
    }
  ]
}

Plusieurs serveurs MCP

Vous pouvez vous connecter à plusieurs serveurs MCP en incluant plusieurs définitions de serveurs dans mcp_servers et un MCPToolset correspondant pour chacun dans le tableau tools :

{
  "model": "claude-opus-4-6",
  "max_tokens": 1000,
  "messages": [
    {
      "role": "user",
      "content": "Use tools from both mcp-server-1 and mcp-server-2 to complete this task"
    }
  ],
  "mcp_servers": [
    {
      "type": "url",
      "url": "https://mcp.example1.com/sse",
      "name": "mcp-server-1",
      "authorization_token": "TOKEN1"
    },
    {
      "type": "url",
      "url": "https://mcp.example2.com/sse",
      "name": "mcp-server-2",
      "authorization_token": "TOKEN2"
    }
  ],
  "tools": [
    {
      "type": "mcp_toolset",
      "mcp_server_name": "mcp-server-1"
    },
    {
      "type": "mcp_toolset",
      "mcp_server_name": "mcp-server-2",
      "default_config": {
        "defer_loading": true
      }
    }
  ]
}

Authentification

Pour les serveurs MCP qui nécessitent une authentification OAuth, vous devrez obtenir un jeton d'accès. La version bêta du connecteur MCP prend en charge le passage d'un paramètre authorization_token dans la définition du serveur MCP. Les consommateurs d'API sont censés gérer le flux OAuth et obtenir le jeton d'accès avant d'effectuer l'appel API, ainsi que de rafraîchir le jeton si nécessaire.

Obtention d'un jeton d'accès pour les tests

L'inspecteur MCP peut vous guider tout au long du processus d'obtention d'un jeton d'accès à des fins de test.

1. Exécutez l'inspecteur avec la commande suivante. Vous devez avoir Node.js installé sur votre machine.

   npx @modelcontextprotocol/inspector

2. Dans la barre latérale gauche, pour "Transport type", sélectionnez "SSE" ou "Streamable HTTP".

3. Entrez l'URL du serveur MCP.

4. Dans la zone de droite, cliquez sur le bouton "Open Auth Settings" après "Need to configure authentication?".

5. Cliquez sur "Quick OAuth Flow" et autorisez sur l'écran OAuth.

6. Suivez les étapes dans la section "OAuth Flow Progress" de l'inspecteur et cliquez sur "Continue" jusqu'à atteindre "Authentication complete".

7. Copiez la valeur access_token.

8. Collez-la dans le champ authorization_token de votre configuration de serveur MCP.

Utilisation du jeton d'accès

Une fois que vous avez obtenu un jeton d'accès en utilisant le flux OAuth ci-dessus, vous pouvez l'utiliser dans votre configuration de serveur MCP :

{
  "mcp_servers": [
    {
      "type": "url",
      "url": "https://example-server.modelcontextprotocol.io/sse",
      "name": "authenticated-server",
      "authorization_token": "YOUR_ACCESS_TOKEN_HERE"
    }
  ]
}

Pour des explications détaillées du flux OAuth, consultez la section Autorisation dans la spécification MCP.

Assistants MCP côté client (TypeScript)

Si vous gérez votre propre connexion client MCP (par exemple, avec des serveurs stdio locaux, des invites MCP ou des ressources MCP), le SDK TypeScript fournit des fonctions d'assistance qui convertissent entre les types MCP et les types de l'API Claude. Cela élimine le code de conversion manuel lors de l'utilisation du SDK MCP avec le SDK Anthropic.

Installation

Installez à la fois le SDK Anthropic et le SDK MCP :

npm install @anthropic-ai/sdk @modelcontextprotocol/sdk

Assistants disponibles

Importez les assistants depuis l'espace de noms bêta :

import {
  mcpTools,
  mcpMessages,
  mcpResourceToContent,
  mcpResourceToFile
} from "@anthropic-ai/sdk/helpers/beta/mcp";

Utiliser les outils MCP

Convertissez les outils MCP pour une utilisation avec le gestionnaire d'outils du SDK, qui gère automatiquement l'exécution des outils :

import Anthropic from "@anthropic-ai/sdk";
import { mcpTools } from "@anthropic-ai/sdk/helpers/beta/mcp";
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

const anthropic = new Anthropic();

// Connect to an MCP server
const transport = new StdioClientTransport({ command: "mcp-server", args: [] });
const mcpClient = new Client({ name: "my-client", version: "1.0.0" });
await mcpClient.connect(transport);

// List tools and convert them for the Claude API
const { tools } = await mcpClient.listTools();
const runner = await anthropic.beta.messages.toolRunner({
  model: "claude-sonnet-4-6",
  max_tokens: 1024,
  messages: [{ role: "user", content: "What tools do you have available?" }],
  tools: mcpTools(tools, mcpClient)
});

Utiliser les invites MCP

Convertissez les messages d'invite MCP au format de message de l'API Claude :

import { mcpMessages } from "@anthropic-ai/sdk/helpers/beta/mcp";

const { messages } = await mcpClient.getPrompt({ name: "my-prompt" });
const response = await anthropic.beta.messages.create({
  model: "claude-sonnet-4-6",
  max_tokens: 1024,
  messages: mcpMessages(messages)
});

Utiliser les ressources MCP

Convertissez les ressources MCP en blocs de contenu à inclure dans les messages, ou en objets fichiers pour le téléversement :

import { mcpResourceToContent, mcpResourceToFile } from "@anthropic-ai/sdk/helpers/beta/mcp";

// As a content block in a message
const resource = await mcpClient.readResource({ uri: "file:///path/to/doc.txt" });
await anthropic.beta.messages.create({
  model: "claude-sonnet-4-6",
  max_tokens: 1024,
  messages: [
    {
      role: "user",
      content: [
        mcpResourceToContent(resource),
        { type: "text", text: "Summarize this document" }
      ]
    }
  ]
});

// As a file upload
const fileResource = await mcpClient.readResource({ uri: "file:///path/to/data.json" });
await anthropic.beta.files.upload({ file: mcpResourceToFile(fileResource) });

Gestion des erreurs

Les fonctions de conversion lèvent UnsupportedMCPValueError si une valeur MCP n'est pas prise en charge par l'API Claude. Cela peut se produire avec des types de contenu non pris en charge, des types MIME ou des liens de ressources non HTTP.

Conservation des données

Le connecteur MCP n'est pas couvert par les arrangements ZDR. Les données échangées avec les serveurs MCP, y compris les définitions d'outils et les résultats d'exécution, sont conservées conformément à la politique de conservation des données standard d'Anthropic.

Pour l'éligibilité ZDR sur toutes les fonctionnalités, consultez API et conservation des données.

Guide de migration

Si vous utilisez l'en-tête bêta déprécié mcp-client-2025-04-04, suivez ce guide pour migrer vers la nouvelle version.

Changements principaux

1. Nouvel en-tête bêta : Passez de mcp-client-2025-04-04 à mcp-client-2025-11-20
2. Configuration des outils déplacée : La configuration des outils se trouve maintenant dans le tableau tools sous forme d'objets MCPToolset, et non dans la définition du serveur MCP
3. Configuration plus flexible : Le nouveau modèle prend en charge les listes d'autorisation, les listes de blocage et la configuration par outil

Étapes de migration

Avant (déprécié) :

{
  "model": "claude-opus-4-6",
  "max_tokens": 1000,
  "messages": [
    // ...
  ],
  "mcp_servers": [
    {
      "type": "url",
      "url": "https://mcp.example.com/sse",
      "name": "example-mcp",
      "authorization_token": "YOUR_TOKEN",
      "tool_configuration": {
        "enabled": true,
        "allowed_tools": ["tool1", "tool2"]
      }
    }
  ]
}

Après (actuel) :

{
  "model": "claude-opus-4-6",
  "max_tokens": 1000,
  "messages": [
    // ...
  ],
  "mcp_servers": [
    {
      "type": "url",
      "url": "https://mcp.example.com/sse",
      "name": "example-mcp",
      "authorization_token": "YOUR_TOKEN"
    }
  ],
  "tools": [
    {
      "type": "mcp_toolset",
      "mcp_server_name": "example-mcp",
      "default_config": {
        "enabled": false
      },
      "configs": {
        "tool1": {
          "enabled": true
        },
        "tool2": {
          "enabled": true
        }
      }
    }
  ]
}

Modèles de migration courants

Version dépréciée : mcp-client-2025-04-04

La version précédente du connecteur MCP incluait la configuration des outils directement dans la définition du serveur MCP :

{
  "mcp_servers": [
    {
      "type": "url",
      "url": "https://example-server.modelcontextprotocol.io/sse",
      "name": "example-mcp",
      "authorization_token": "YOUR_TOKEN",
      "tool_configuration": {
        "enabled": true,
        "allowed_tools": ["example_tool_1", "example_tool_2"]
      }
    }
  ]
}

Descriptions des champs dépréciés