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 :

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

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 :

Fusion de configuration

Les valeurs de configuration fusionnent avec cette priorité (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ésulte en :

• 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 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"
    }
  ]
}

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-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. 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 de faire l'appel API, ainsi que d'actualiser le jeton selon les besoins.

Obtenir 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 "Type de transport", sélectionnez soit "SSE" soit "HTTP Streamable".

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 dans 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 d'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 l'exécuteur d'outils du SDK, qui gère l'exécution des outils automatiquement :

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-5',
  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 d'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-5',
  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-5',
  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.

Guide de migration

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

Changements clés

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 en tant qu'objets MCPToolset, pas dans la définition du serveur MCP
3. Configuration plus flexible : Le nouveau modèle supporte les listes blanches, les listes noires et la configuration par outil

Étapes de migration

Avant (dépréciée) :

{
  "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 (actuelle) :

{
  "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