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 clés

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

Limitations

• De 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 (supporte à la fois les transports HTTP Streamable 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 basique

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

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-4-7",
    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"}],
    betas=["mcp-client-2025-11-20"],
)

print(response)

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

L'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 basique

{
  "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) supporte les champs suivants :

Pour le répertoire complet des outils fournis par Anthropic et les propriétés optionnelles comme defer_loading, consultez la référence des outils. Pour rechercher dans de grands ensembles d'outils, consultez Tool search tool.

Fusion de la configuration

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

1. Paramètres spécifiques aux outils 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ésultats :

• search_events : enabled: false (de configs), defer_loading: true (de default_config)
• Tous les autres outils : enabled: true (valeur par défaut du système), defer_loading: true (de 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 blanche - 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 noire - 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 blanche avec configuration par outil

Combinez la création d'une liste blanche 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 renvoyé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"
    }
  ]
}

Serveurs MCP multiples

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

{
  "model": "claude-opus-4-7",
  "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. Le bêta du connecteur MCP supporte 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 d'actualiser le jeton selon les besoins.

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

L'inspecteur MCP peut vous guider dans le 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 sur la gauche, pour "Transport type", sélectionnez soit "SSE" soit "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 de 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 l'un des 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 aux côtés du 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 utilisation avec le tool runner du SDK, qui gère l'exécution des outils automatiquement :

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 fichier pour téléchargement :

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 standard de conservation des données d'Anthropic.

Pour l'admissibilité ZDR dans 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 clés

1. Nouvel en-tête bêta : Changez 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 en tant qu'objets MCPToolset, pas dans la définition du serveur MCP
3. Configuration plus flexible : Le nouveau modèle supporte la création de listes blanches, de listes noires et la configuration par outil

Étapes de migration

Avant (déprécié) :

{
  "model": "claude-opus-4-7",
  "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-7",
  "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