---
title: Connecteur MCP
url: https://platform.claude.com/docs/fr/agents-and-tools/mcp-connector
description: Connectez-vous à des serveurs MCP distants directement depuis l'API Messages sans client MCP, et autorisez, bloquez ou configurez des outils individuels.
featureMetadata:
status: beta
betaHeader: mcp-client-2025-11-20
zdr: not-eligible
supportedPlatforms:
Claude API: beta
Claude Platform on AWS: beta
Microsoft Foundry: beta
---
La fonctionnalité de connecteur « Model Context Protocol », ou MCP, de Claude vous permet de vous connecter à des serveurs MCP distants directement depuis l'API Messages sans client MCP séparé.
La version précédente de cette fonctionnalité (`mcp-client-2025-04-04`) est dépréciée. Consultez [Version dépréciée : mcp-client-2025-04-04](https://platform.claude.com/docs/fr/agents-and-tools/mcp-connector#deprecated-version-mcp-client-2025-04-04).
## Fonctionnalités clés
* **Intégration directe à l'API :** connectez-vous à des serveurs MCP sans implémenter de client MCP
* **Prise en charge de l'appel d'outils :** accédez aux outils MCP via l'API Messages
* **Configuration flexible des outils :** activez tous les outils, autorisez des outils spécifiques (allowlist) ou bloquez les outils indésirables (denylist)
* **Configuration par outil :** configurez des outils individuels avec des paramètres personnalisés
* **Authentification OAuth :** prise en charge des jetons Bearer OAuth pour les serveurs authentifiés
* **Serveurs multiples :** connectez-vous à plusieurs serveurs MCP dans une seule requête
## Quand Claude utilise les outils MCP
Une fois qu'un serveur MCP est connecté, Claude appelle ses outils lorsque la requête de l'utilisateur correspond à la capacité décrite d'un outil, soit explicitement (« recherche les bugs ouverts dans Jira »), soit implicitement (« qu'est-ce qui bloque la publication ? » avec un serveur Jira attaché).
Claude n'appelle **pas** un outil MCP pour des questions de connaissances générales sur un service connecté. Demander « comment fonctionnent les bases de données Notion ? » avec un serveur Notion attaché reçoit une réponse directe ; demander « que contient ma base de données Projets ? » déclenche l'outil.
Vous pouvez orienter la propension de Claude à appeler les outils MCP via votre invite système. Consultez [Quand Claude utilise les outils](https://platform.claude.com/docs/fr/agents-and-tools/tool-use/overview#when-claude-uses-tools) pour des conseils généraux et des exemples de formulations.
## Limitations
* Parmi l'ensemble des fonctionnalités de la [spécification MCP](https://modelcontextprotocol.io/introduction#explore-mcp), seuls les [appels d'outils](https://modelcontextprotocol.io/docs/concepts/tools) 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.
## 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 quels 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 :
```bash cURL
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-5-5",
"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"
}
]
}'
```
```bash CLI
ant beta:messages create --beta mcp-client-2025-11-20 <<'YAML'
model: claude-opus-5-5
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
YAML
```
```python Python
client = anthropic.Anthropic()
response = client.beta.messages.create(
model="claude-opus-5-5",
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)
```
```typescript TypeScript
const anthropic = new Anthropic();
const response = await anthropic.beta.messages.create({
model: "claude-opus-5-5",
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"]
});
console.log(response);
```
```csharp C#
AnthropicClient client = new();
var parameters = new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 1000,
Messages = new List
{
new() { Role = Role.User, Content = "What tools do you have available?" }
},
McpServers = new List
{
new()
{
Url = "https://example-server.modelcontextprotocol.io/sse",
Name = "example-mcp",
AuthorizationToken = "YOUR_TOKEN"
}
},
Tools = new List
{
new BetaMcpToolset("example-mcp")
},
Betas = [AnthropicBeta.McpClient2025_11_20]
};
var message = await client.Beta.Messages.Create(parameters);
Console.WriteLine(message);
```
```go Go
client := anthropic.NewClient()
response, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1000,
Messages: []anthropic.BetaMessageParam{
anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("What tools do you have available?")),
},
MCPServers: []anthropic.BetaRequestMCPServerURLDefinitionParam{
{
URL: "https://example-server.modelcontextprotocol.io/sse",
Name: "example-mcp",
AuthorizationToken: anthropic.String("YOUR_TOKEN"),
},
},
Tools: []anthropic.BetaToolUnionParam{
{OfMCPToolset: &anthropic.BetaMCPToolsetParam{
MCPServerName: "example-mcp",
}},
},
Betas: []anthropic.AnthropicBeta{
anthropic.AnthropicBetaMCPClient2025_11_20,
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(response)
```
```java Java
import com.anthropic.models.beta.messages.BetaMcpToolset;
// ...
import com.anthropic.models.beta.messages.BetaRequestMcpServerUrlDefinition;
// ...
void main() {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1000L)
.addUserMessage("What tools do you have available?")
.addMcpServer(BetaRequestMcpServerUrlDefinition.builder()
.url("https://example-server.modelcontextprotocol.io/sse")
.name("example-mcp")
.authorizationToken("YOUR_TOKEN")
.build())
.addTool(BetaMcpToolset.builder()
.mcpServerName("example-mcp")
.build())
.addBeta(AnthropicBeta.MCP_CLIENT_2025_11_20)
.build();
BetaMessage response = client.beta().messages().create(params);
IO.println(response);
}
```
```php PHP
$client = new Client();
$message = $client->beta->messages->create(
maxTokens: 1000,
messages: [
['role' => 'user', 'content' => 'What tools do you have available?']
],
model: 'claude-opus-5-5',
mcpServers: [
[
'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'],
);
echo $message;
```
```ruby Ruby
client = Anthropic::Client.new
response = client.beta.messages.create(
model: "claude-opus-5-5",
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"]
)
puts response
```
## Configuration du serveur MCP
Chaque serveur MCP dans le tableau `mcp_servers` définit les détails de connexion :
```json
{
"type": "url",
"url": "https://example-server.modelcontextprotocol.io/sse",
"name": "example-mcp",
"authorization_token": "YOUR_TOKEN"
}
```
### Description des champs
| Propriété | Type | Obligatoire | Description |
| --------------------- | ------ | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | string | Oui | Actuellement, seul "url" est pris en charge. |
| `url` | string | Oui | L'URL du serveur MCP. Doit commencer par https\://. |
| `name` | string | Oui | Un identifiant unique pour ce serveur MCP. Doit être référencé par exactement un MCPToolset dans le tableau `tools`. |
| `authorization_token` | string | Non | Jeton d'autorisation OAuth si requis par le serveur MCP. Consultez [Authentification](https://platform.claude.com/docs/fr/agents-and-tools/mcp-connector#authentication) pour savoir comment en obtenir un, ou la [spécification MCP](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization) pour les détails du protocole. |
## Configuration de l'ensemble d'outils MCP
Le MCPToolset se trouve dans le tableau `tools` et configure quels outils du serveur MCP sont activés et comment ils doivent être configurés.
### Structure de base
```json
{
"type": "mcp_toolset",
"mcp_server_name": "example-mcp",
"default_config": {
"enabled": true,
"defer_loading": false
},
"configs": {
"specific_tool_name": {
"enabled": true,
"defer_loading": true
}
}
}
```
### Description des champs
| Propriété | Type | Obligatoire | Description |
| ----------------- | ------ | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | string | Oui | Doit être « mcp\_toolset ». |
| `mcp_server_name` | string | Oui | Doit correspondre à un nom de serveur défini dans le tableau `mcp_servers`. |
| `default_config` | object | Non | Configuration par défaut appliquée à tous les outils de cet ensemble. Les configurations d'outils individuelles dans `configs` remplacent ces valeurs par défaut. |
| `configs` | object | Non | Remplacements de configuration par outil. Les clés sont les noms des outils, les valeurs sont des objets de configuration. |
| `cache_control` | object | Non | Configuration du point d'arrêt de cache de la [mise en cache des prompts](https://platform.claude.com/docs/fr/build-with-claude/prompt-caching) pour cet ensemble d'outils. |
Avec l'en-tête bêta `mcp-client-2026-09-15`, un MCPToolset accepte également `tools`, une copie épinglée de la liste d'outils du serveur. Consultez [Épingler la liste d'outils d'un serveur MCP](https://platform.claude.com/docs/fr/agents-and-tools/mcp-connector#pin-mcp-tool-list).
### Options de configuration des outils
Chaque outil (qu'il soit configuré dans `default_config` ou dans `configs`) prend en charge les champs suivants :
| Propriété | Type | Valeur par défaut | Description |
| --------------- | ------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `enabled` | boolean | `true` | Indique si cet outil est activé. |
| `defer_loading` | boolean | `false` | Si true, la description de l'outil n'est pas envoyée au modèle initialement. Utilisé avec l'[outil de recherche d'outils](https://platform.claude.com/docs/fr/agents-and-tools/tool-use/tool-search-tool). |
Pour le répertoire complet des outils fournis par Anthropic et des propriétés optionnelles telles que `defer_loading`, consultez la [référence des outils](https://platform.claude.com/docs/fr/agents-and-tools/tool-use/tool-reference). Pour effectuer des recherches dans de grands ensembles d'outils, consultez l'[outil de recherche d'outils](https://platform.claude.com/docs/fr/agents-and-tools/tool-use/tool-search-tool).
### Fusion des configurations
Les valeurs de configuration fusionnent selon cet ordre de priorité (du plus élevé au plus bas) :
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 :
```json
{
"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 :
```json
{
"type": "mcp_toolset",
"mcp_server_name": "google-calendar-mcp"
}
```
### Allowlist : activer uniquement des outils spécifiques
Définissez `enabled: false` comme valeur par défaut, puis activez explicitement des outils spécifiques :
```json
{
"type": "mcp_toolset",
"mcp_server_name": "google-calendar-mcp",
"default_config": {
"enabled": false
},
"configs": {
"search_events": {
"enabled": true
},
"create_event": {
"enabled": true
}
}
}
```
### Denylist : désactiver des outils spécifiques
Activez tous les outils par défaut, puis désactivez explicitement les outils indésirables. Il est recommandé de bloquer les outils d'écriture ou destructifs lors de la création d'assistants en lecture seule, ou lorsque vous souhaitez une étape de confirmation humaine avant les changements d'état :
```json
{
"type": "mcp_toolset",
"mcp_server_name": "google-calendar-mcp",
"configs": {
"delete_all_events": {
"enabled": false
},
"share_calendar_publicly": {
"enabled": false
}
}
}
```
### Mixte : allowlist avec configuration par outil
Combinez l'allowlist avec une configuration personnalisée pour chaque outil :
```json
{
"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 est consigné côté backend 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 inclut deux nouveaux types de blocs de contenu :
### Bloc d'utilisation d'outil MCP
```json
{
"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
```json
{
"type": "mcp_tool_result",
"tool_use_id": "mcptoolu_014Q35RayjACSWkSj4X2yov1",
"is_error": false,
"content": [
{
"type": "text",
"text": "Hello"
}
]
}
```
## Épingler la liste d'outils d'un serveur MCP (bêta)
Un serveur MCP peut modifier ses outils à tout moment. L'en-tête bêta `mcp-client-2026-09-15` enregistre la liste d'outils renvoyée par chaque serveur et vous permet de l'épingler, de sorte qu'un serveur qui modifie ses outils ne change pas ce que Claude voit en cours de conversation. Il inclut tout ce que fait `mcp-client-2025-11-20` ; envoyez-le donc à la place de cet en-tête. Il est disponible sur l'API Claude.
Lorsque l'API demande ses outils à un serveur MCP pendant la production d'une réponse, la réponse commence par un bloc `mcp_tool_listing` pour ce serveur, un bloc pour chaque serveur interrogé :
```json
{
"type": "mcp_tool_listing",
"mcp_server_name": "example-mcp",
"tools": [
{
"name": "echo",
"description": "Returns the text it receives.",
"input_schema": {
"type": "object",
"properties": { "text": { "type": "string" } },
"required": ["text"]
}
}
]
}
```
Si votre code lit `content[0]`, ignorez ces blocs. Renvoyez le message de l'assistant sans modification, blocs `mcp_tool_listing` compris, et continuez à envoyer `mcp-client-2026-09-15` dans chaque requête qui en contient un. Les requêtes suivantes utilisent alors la liste enregistrée pour ce serveur au lieu de l'interroger à nouveau.
Pour épingler vous-même une liste, copiez le champ `tools` d'un bloc dans le champ `tools` du MCPToolset de ce serveur. L'API ne demande alors plus ses outils au serveur, et les outils de l'ensemble sont exactement ces entrées, avec `default_config` et `configs` appliqués :
```json
{
"type": "mcp_toolset",
"mcp_server_name": "example-mcp",
"tools": [
{
"name": "echo",
"description": "Returns the text it receives.",
"input_schema": {
"type": "object",
"properties": { "text": { "type": "string" } },
"required": ["text"]
}
}
]
}
```
Chaque entrée de `tools` contient le `name` de l'outil tel que le serveur le liste (sans le nom du serveur), sa `description` et son `input_schema`.
L'exemple suivant envoie une requête avec un ensemble d'outils non épinglé, copie la liste renvoyée dans le champ `tools` de l'ensemble d'outils, puis envoie à nouveau la requête. La seconde réponse ne contient aucun bloc `mcp_tool_listing`, car l'API n'interroge pas le serveur :
```bash cURL
BODY='{
"model": "claude-opus-5-5",
"max_tokens": 1024,
"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"
}
],
"messages": [
{
"role": "user",
"content": "What tools do you have available?"
}
]
}'
# Première requête : le toolset n'est pas épinglé, donc l'API demande au serveur
# ses outils et la réponse commence par un bloc mcp_tool_listing.
# tee affiche la réponse sur stderr pendant que la variable la capture.
FIRST=$(curl -sS 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-2026-09-15" \
-d "$BODY" | tee /dev/stderr)
# Épinglez la liste : copiez les outils du bloc dans le toolset. L'API utilise
# exactement ces entrées et n'interroge plus le serveur.
TOOLS=$(jq '.content[] | select(.type == "mcp_tool_listing") | .tools' \
<<<"$FIRST")
PINNED=$(jq --argjson tools "$TOOLS" '.tools[0].tools = $tools' <<<"$BODY")
# Avec un toolset épinglé, la réponse ne contient aucun bloc mcp_tool_listing.
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-2026-09-15" \
-d "$PINNED"
```
```bash CLI
request=$(cat <<'YAML'
model: claude-opus-5-5
max_tokens: 1024
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
messages:
- role: user
content: What tools do you have available?
YAML
)
# Première requête : le toolset n'est pas épinglé, donc l'API demande au serveur
# ses outils et la réponse commence par un bloc mcp_tool_listing.
# tee affiche la réponse sur stderr pendant que la variable la capture.
first=$(ant beta:messages create --beta mcp-client-2026-09-15 --format json \
<<<"$request" | tee /dev/stderr)
tools=$(jq -c '.content[] | select(.type == "mcp_tool_listing") | .tools' \
<<<"$first")
# Épinglez la liste : copiez les outils du bloc dans le toolset. L'option --tool
# remplace le tableau tools du corps. L'API utilise exactement ces entrées et
# ne réinterroge pas le serveur, donc la réponse n'a pas de bloc mcp_tool_listing.
ant beta:messages create --beta mcp-client-2026-09-15 \
--tool "{type: mcp_toolset, mcp_server_name: example-mcp, tools: $tools}" \
<<<"$request"
```
```python Python
from anthropic.types.beta import (
BetaMessageParam,
BetaRequestMCPServerURLDefinitionParam,
)
client = anthropic.Anthropic()
mcp_servers: list[BetaRequestMCPServerURLDefinitionParam] = [
{
"type": "url",
"url": "https://example-server.modelcontextprotocol.io/sse",
"name": "example-mcp",
"authorization_token": "YOUR_TOKEN",
},
]
messages: list[BetaMessageParam] = [
{"role": "user", "content": "What tools do you have available?"},
]
# Première requête : le toolset n'est pas épinglé, donc l'API demande au serveur
# ses outils et la réponse commence par un bloc mcp_tool_listing.
first = client.beta.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
betas=["mcp-client-2026-09-15"],
mcp_servers=mcp_servers,
tools=[{"type": "mcp_toolset", "mcp_server_name": "example-mcp"}],
messages=messages,
)
listing = next(block for block in first.content if block.type == "mcp_tool_listing")
print([tool.name for tool in listing.tools])
# Épinglez la liste : copiez les outils du bloc dans le toolset. L'API utilise
# exactement ces entrées et n'interroge plus le serveur.
second = client.beta.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
betas=["mcp-client-2026-09-15"],
mcp_servers=mcp_servers,
tools=[
{
"type": "mcp_toolset",
"mcp_server_name": "example-mcp",
"tools": [
{
"name": tool.name,
"description": tool.description,
"input_schema": tool.input_schema,
}
for tool in listing.tools
],
},
],
messages=messages,
)
# Avec un toolset épinglé, la réponse ne contient aucun bloc mcp_tool_listing.
print([block.type for block in second.content])
```
```typescript TypeScript
const client = new Anthropic();
const mcpServers: Anthropic.Beta.BetaRequestMCPServerURLDefinition[] = [
{
type: "url",
url: "https://example-server.modelcontextprotocol.io/sse",
name: "example-mcp",
authorization_token: "YOUR_TOKEN"
}
];
const messages: Anthropic.Beta.BetaMessageParam[] = [
{ role: "user", content: "What tools do you have available?" }
];
// Première requête : le toolset n'est pas épinglé, donc l'API demande au serveur
// ses outils et la réponse commence par un bloc mcp_tool_listing.
const first = await client.beta.messages.create({
model: "claude-opus-5-5",
max_tokens: 1024,
betas: ["mcp-client-2026-09-15"],
mcp_servers: mcpServers,
tools: [{ type: "mcp_toolset", mcp_server_name: "example-mcp" }],
messages
});
const listing = first.content.find((block) => block.type === "mcp_tool_listing");
if (!listing) {
throw new Error("The response has no mcp_tool_listing block.");
}
console.log(listing.tools.map((tool) => tool.name));
// Épinglez la liste : copiez les outils du bloc dans le toolset. L'API utilise
// exactement ces entrées et n'interroge plus le serveur.
const second = await client.beta.messages.create({
model: "claude-opus-5-5",
max_tokens: 1024,
betas: ["mcp-client-2026-09-15"],
mcp_servers: mcpServers,
tools: [
{
type: "mcp_toolset",
mcp_server_name: "example-mcp",
tools: listing.tools
}
],
messages
});
// Avec un toolset épinglé, la réponse ne contient aucun bloc mcp_tool_listing.
console.log(second.content.map((block) => block.type));
```
```csharp C#
using Anthropic.Models.Beta;
using Anthropic.Models.Beta.Messages;
using Messages = Anthropic.Models.Messages;
AnthropicClient client = new();
List mcpServers =
[
new()
{
Url = "https://example-server.modelcontextprotocol.io/sse",
Name = "example-mcp",
AuthorizationToken = "YOUR_TOKEN",
},
];
List messages =
[
new() { Role = Role.User, Content = "What tools do you have available?" },
];
// Première requête : le toolset n'est pas épinglé, donc l'API demande au serveur
// ses outils et la réponse commence par un bloc mcp_tool_listing.
var first = await client.Beta.Messages.Create(new MessageCreateParams
{
Model = Messages::Model.ClaudeOpus5_5,
MaxTokens = 1024,
Betas = [AnthropicBeta.McpClient2026_09_15],
McpServers = mcpServers,
Tools = [new BetaMcpToolset("example-mcp")],
Messages = messages,
});
var listing = first.Content
.Select(block => block.Value)
.OfType()
.First();
Console.WriteLine(string.Join(", ", listing.Tools.Select(tool => tool.Name)));
// Épinglez la liste : copiez les outils du bloc dans le toolset. L'API utilise
// exactement ces entrées et n'interroge plus le serveur.
var second = await client.Beta.Messages.Create(new MessageCreateParams
{
Model = Messages::Model.ClaudeOpus5_5,
MaxTokens = 1024,
Betas = [AnthropicBeta.McpClient2026_09_15],
McpServers = mcpServers,
Tools =
[
new BetaMcpToolset("example-mcp")
{
Tools =
[
.. listing.Tools.Select(tool => new BetaMcpToolParam
{
Name = tool.Name,
Description = tool.Description,
InputSchema = tool.InputSchema,
}),
],
},
],
Messages = messages,
});
// Avec un toolset épinglé, la réponse ne contient aucun bloc mcp_tool_listing.
Console.WriteLine(string.Join(", ", second.Content.Select(block => block.Type)));
```
```go Go
client := anthropic.NewClient()
mcpServers := []anthropic.BetaRequestMCPServerURLDefinitionParam{
{
URL: "https://example-server.modelcontextprotocol.io/sse",
Name: "example-mcp",
AuthorizationToken: anthropic.String("YOUR_TOKEN"),
},
}
messages := []anthropic.BetaMessageParam{
anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("What tools do you have available?")),
}
// Première requête : le toolset n'est pas épinglé, donc l'API demande au serveur
// ses outils et la réponse commence par un bloc mcp_tool_listing.
first, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1024,
Betas: []anthropic.AnthropicBeta{anthropic.AnthropicBetaMCPClient2026_09_15},
MCPServers: mcpServers,
Tools: []anthropic.BetaToolUnionParam{
{OfMCPToolset: &anthropic.BetaMCPToolsetParam{MCPServerName: "example-mcp"}},
},
Messages: messages,
})
if err != nil {
log.Fatal(err)
}
var listing anthropic.BetaMCPToolListingBlock
for _, block := range first.Content {
if listingBlock, ok := block.AsAny().(anthropic.BetaMCPToolListingBlock); ok {
listing = listingBlock
break
}
}
// Épinglez la liste : copiez les outils du bloc dans le toolset. L'API utilise
// exactement ces entrées et n'interroge plus le serveur.
var toolNames []string
var pinnedTools []anthropic.BetaMCPToolParam
for _, tool := range listing.Tools {
toolNames = append(toolNames, tool.Name)
pinnedTools = append(pinnedTools, anthropic.BetaMCPToolParam{
Name: tool.Name,
Description: anthropic.String(tool.Description),
InputSchema: tool.InputSchema,
})
}
fmt.Println(toolNames)
second, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1024,
Betas: []anthropic.AnthropicBeta{anthropic.AnthropicBetaMCPClient2026_09_15},
MCPServers: mcpServers,
Tools: []anthropic.BetaToolUnionParam{
{OfMCPToolset: &anthropic.BetaMCPToolsetParam{
MCPServerName: "example-mcp",
Tools: pinnedTools,
}},
},
Messages: messages,
})
if err != nil {
log.Fatal(err)
}
// Avec un toolset épinglé, la réponse ne contient aucun bloc mcp_tool_listing.
var blockTypes []string
for _, block := range second.Content {
blockTypes = append(blockTypes, block.Type)
}
fmt.Println(blockTypes)
```
```java Java
import com.anthropic.models.beta.AnthropicBeta;
import com.anthropic.models.beta.messages.BetaMcpTool;
import com.anthropic.models.beta.messages.BetaMcpToolListingBlock;
import com.anthropic.models.beta.messages.BetaMcpToolset;
import com.anthropic.models.beta.messages.BetaMessage;
import com.anthropic.models.beta.messages.BetaRequestMcpServerUrlDefinition;
import com.anthropic.models.beta.messages.MessageCreateParams;
// ...
void main() {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
BetaRequestMcpServerUrlDefinition mcpServer = BetaRequestMcpServerUrlDefinition.builder()
.url("https://example-server.modelcontextprotocol.io/sse")
.name("example-mcp")
.authorizationToken("YOUR_TOKEN")
.build();
// Première requête : le toolset n'est pas épinglé, donc l'API demande au serveur
// ses outils et la réponse commence par un bloc mcp_tool_listing.
BetaMessage first = client.beta().messages().create(MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1024)
.addBeta(AnthropicBeta.MCP_CLIENT_2026_09_15)
.addMcpServer(mcpServer)
.addTool(BetaMcpToolset.builder()
.mcpServerName("example-mcp")
.build())
.addUserMessage("What tools do you have available?")
.build());
BetaMcpToolListingBlock listing = first.content().stream()
.flatMap(block -> block.mcpToolListing().stream())
.findFirst()
.orElseThrow();
IO.println(listing.tools().stream().map(BetaMcpTool::name).toList());
// Épinglez la liste : copiez les outils du bloc dans le toolset. L'API utilise
// exactement ces entrées et n'interroge plus le serveur.
BetaMessage second = client.beta().messages().create(MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1024)
.addBeta(AnthropicBeta.MCP_CLIENT_2026_09_15)
.addMcpServer(mcpServer)
.addTool(BetaMcpToolset.builder()
.mcpServerName("example-mcp")
.tools(listing.tools().stream().map(BetaMcpTool::toParam).toList())
.build())
.addUserMessage("What tools do you have available?")
.build());
// Avec un toolset épinglé, la réponse ne contient aucun bloc mcp_tool_listing.
IO.println(second.content().stream()
.map(block -> block.type().asString())
.toList());
}
```
```php PHP
use Anthropic\Beta\AnthropicBeta;
use Anthropic\Beta\Messages\BetaMCPTool;
use Anthropic\Beta\Messages\BetaMCPToolListingBlock;
// ...
$client = new Client();
$mcpServers = [
[
'type' => 'url',
'url' => 'https://example-server.modelcontextprotocol.io/sse',
'name' => 'example-mcp',
'authorization_token' => 'YOUR_TOKEN',
],
];
$messages = [['role' => 'user', 'content' => 'What tools do you have available?']];
// Première requête : le toolset n'est pas épinglé, donc l'API demande au serveur
// ses outils et la réponse commence par un bloc mcp_tool_listing.
$first = $client->beta->messages->create(
model: Model::CLAUDE_OPUS_5_5,
maxTokens: 1024,
betas: [AnthropicBeta::MCP_CLIENT_2026_09_15],
mcpServers: $mcpServers,
tools: [['type' => 'mcp_toolset', 'mcp_server_name' => 'example-mcp']],
messages: $messages,
);
$listing = array_find($first->content, fn ($block) => $block instanceof BetaMCPToolListingBlock);
echo json_encode(array_map(fn (BetaMCPTool $tool) => $tool->name, $listing->tools)), PHP_EOL;
// Épinglez la liste : copiez les outils du bloc dans le toolset. L'API utilise
// exactement ces entrées et n'interroge plus le serveur.
$second = $client->beta->messages->create(
model: Model::CLAUDE_OPUS_5_5,
maxTokens: 1024,
betas: [AnthropicBeta::MCP_CLIENT_2026_09_15],
mcpServers: $mcpServers,
tools: [
[
'type' => 'mcp_toolset',
'mcp_server_name' => 'example-mcp',
'tools' => array_map(
fn (BetaMCPTool $tool) => [
'name' => $tool->name,
'description' => $tool->description,
'input_schema' => $tool->inputSchema,
],
$listing->tools,
),
],
],
messages: $messages,
);
// Avec un toolset épinglé, la réponse ne contient aucun bloc mcp_tool_listing.
echo json_encode(array_map(fn ($block) => $block->type, $second->content)), PHP_EOL;
```
```ruby Ruby
client = Anthropic::Client.new
mcp_servers = [
{
type: "url",
url: "https://example-server.modelcontextprotocol.io/sse",
name: "example-mcp",
authorization_token: "YOUR_TOKEN"
}
]
messages = [{ role: "user", content: "What tools do you have available?" }]
# Première requête : le toolset n'est pas épinglé, donc l'API demande au serveur
# ses outils et la réponse commence par un bloc mcp_tool_listing.
first = client.beta.messages.create(
model: Anthropic::Model::CLAUDE_OPUS_5_5,
max_tokens: 1024,
betas: [Anthropic::AnthropicBeta::MCP_CLIENT_2026_09_15],
mcp_servers:,
tools: [{ type: "mcp_toolset", mcp_server_name: "example-mcp" }],
messages:
)
listing = first.content.find { it.is_a?(Anthropic::Beta::BetaMCPToolListingBlock) }
puts listing.tools.map(&:name).inspect
# Épinglez la liste : copiez les outils du bloc dans le toolset. L'API utilise
# exactement ces entrées et n'interroge plus le serveur.
second = client.beta.messages.create(
model: Anthropic::Model::CLAUDE_OPUS_5_5,
max_tokens: 1024,
betas: [Anthropic::AnthropicBeta::MCP_CLIENT_2026_09_15],
mcp_servers:,
tools: [
{
type: "mcp_toolset",
mcp_server_name: "example-mcp",
tools: listing.tools.map(&:to_h)
}
],
messages:
)
# Avec un toolset épinglé, la réponse ne contient aucun bloc mcp_tool_listing.
puts second.content.map(&:type).inspect
```
Si vous utilisez également l'en-tête bêta `inline-tools-2026-09-15`, vous pouvez ajouter un serveur MCP en cours de conversation. Consultez [Ajouter un serveur MCP en cours de conversation](https://platform.claude.com/docs/fr/build-with-claude/mid-conversation-system-messages#add-an-mcp-server-mid-conversation-beta).
## Serveurs MCP multiples
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` :
```json
{
"model": "claude-opus-5-5",
"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
}
}
]
}
```
Lorsque de nombreux outils sont disponibles, Claude effectue sa sélection en fonction des noms et descriptions des outils. Des descriptions d'outils claires et spécifiques améliorent la précision de la sélection. Pour les grands ensembles d'outils (des dizaines d'outils répartis sur plusieurs serveurs), envisagez d'activer [`defer_loading`](https://platform.claude.com/docs/fr/agents-and-tools/mcp-connector#tool-configuration-options) avec l'[outil de recherche d'outils](https://platform.claude.com/docs/fr/agents-and-tools/tool-use/tool-search-tool) afin que seuls les outils pertinents soient présentés pour chaque requête.
## Authentification
Pour les serveurs MCP qui nécessitent une authentification OAuth, vous devrez obtenir un jeton d'accès. La bêta du connecteur MCP prend en charge la transmission d'un paramètre `authorization_token` dans la définition du serveur MCP. Les consommateurs de l'API sont censés gérer le flux OAuth et obtenir le jeton d'accès avant d'effectuer l'appel API, ainsi que rafraîchir le jeton si nécessaire.
### Obtenir 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. Node.js doit être installé sur votre machine.
```bash
npx @modelcontextprotocol/inspector
```
2. Dans la barre latérale de gauche, pour **Transport type**, sélectionnez **SSE** ou **Streamable HTTP**.
3. Saisissez l'URL du serveur MCP.
4. Dans la zone de droite, cliquez sur **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 à l'aide de l'un des flux OAuth précédents, vous pouvez l'utiliser dans votre configuration de serveur MCP :
```json
{
"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 sur le flux OAuth, reportez-vous à la [section Authorization](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization) de la spécification MCP.
## Assistants MCP côté client
Si vous gérez votre propre connexion client MCP (par exemple, avec des serveurs stdio locaux, des prompts MCP ou des ressources MCP), le SDK fournit des fonctions d'assistance qui effectuent la conversion entre les types MCP et les types de l'API Claude. Cela élimine le code de conversion manuel lorsque vous utilisez un SDK MCP pour votre langage (par exemple, le [SDK MCP TypeScript](https://github.com/modelcontextprotocol/typescript-sdk)) conjointement avec le SDK Anthropic.
Utilisez le [paramètre d'API `mcp_servers`](https://platform.claude.com/docs/fr/agents-and-tools/mcp-connector#using-the-mcp-connector-in-the-messages-api) lorsque vous disposez de serveurs distants accessibles par URL et que vous n'avez besoin que de la prise en charge des outils. Utilisez les assistants côté client lorsque vous avez besoin de serveurs locaux, de prompts, de ressources ou d'un contrôle accru sur la connexion avec le SDK de base.
### Installation
Installez à la fois le SDK Anthropic et le SDK MCP :
Les assistants MCP sont inclus dans l'extra `mcp`, qui nécessite Python 3.10 ou une version ultérieure :
```bash
pip install "anthropic[mcp]"
```
```bash
npm install @anthropic-ai/sdk @modelcontextprotocol/sdk
```
Les assistants se trouvent dans le package distinct `Anthropic.Mcp` ; le client MCP lui-même provient du [package ModelContextProtocol](https://www.nuget.org/packages/ModelContextProtocol) officiel :
```bash
dotnet add package Anthropic.Mcp
dotnet add package ModelContextProtocol
```
Les assistants se trouvent dans le sous-package `mcp` du SDK Go, qui s'appuie sur le [SDK MCP Go](https://github.com/modelcontextprotocol/go-sdk) :
```bash
go get github.com/anthropics/anthropic-sdk-go/mcp
```
Les assistants se trouvent dans l'artefact distinct `anthropic-java-mcp`, qui nécessite Java 17 ou une version ultérieure (le SDK de base prend en charge Java 8). Ajoutez-le à côté de la dépendance de base `anthropic-java` :
```kotlin
implementation("com.anthropic:anthropic-java:2.73.0")
implementation("com.anthropic:anthropic-java-mcp:2.73.0")
```
```xml
com.anthropic
anthropic-java
2.73.0
com.anthropic
anthropic-java-mcp
2.73.0
```
Les assistants utilisent le [SDK MCP PHP](https://packagist.org/packages/mcp/sdk) officiel :
```bash
composer require "anthropic-ai/sdk" "guzzlehttp/guzzle:^7" "mcp/sdk"
```
Les assistants utilisent la [gem `mcp`](https://rubygems.org/gems/mcp) officielle :
```bash
bundle add anthropic mcp
```
### Assistants disponibles
Importez les assistants pour votre langage :
```python Python
from anthropic.lib.tools.mcp import (
async_mcp_tool,
mcp_message,
mcp_resource_to_content,
mcp_resource_to_file,
)
```
```typescript TypeScript
import {
mcpTools,
mcpMessages,
mcpResourceToContent,
mcpResourceToFile
} from "@anthropic-ai/sdk/helpers/beta/mcp";
```
```csharp C#
using Anthropic.Helpers.Beta;
using Anthropic.Helpers.Beta.Mcp;
```
```go Go
import (
"github.com/anthropics/anthropic-sdk-go/mcp"
)
```
```java Java
import com.anthropic.helpers.McpBetaTool;
import com.anthropic.mcp.BetaMcp;
```
```php PHP
use Anthropic\Lib\Tools\BetaMcp;
```
```ruby Ruby
require "anthropic"
# Les helpers sont exposés sur le module Anthropic::Mcp
```
| Assistant | Description |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `async_mcp_tool(tool, mcp_client)` (typescript: `mcpTools(tools, mcpClient)`; csharp: `BetaMcp.ListToolsAsync(mcpClient)`; go: `mcp.NewBetaTools(tools, session)`; java: `BetaMcp.mcpTools(tools, mcpClient)`; php: `BetaMcp::tools($tools, $mcp)`; ruby: `Anthropic::Mcp.tools(tools, mcp_client)`) | Convertit les outils MCP en outils de l'API Claude à utiliser avec `client.beta.messages.tool_runner()` (typescript: `client.beta.messages.toolRunner()`; java: `client.beta().messages().toolRunner()`; php: `$client->beta->messages->toolRunner()`; csharp: `client.Beta.Messages.ToolRunner()`; go: `client.Beta.Messages.NewToolRunner()`) |
| `mcp_message(message)` (typescript: `mcpMessages(messages)`; csharp: `BetaMcp.Messages(messages)`; go: `mcp.ToMessage(message)`; java: `BetaMcp.mcpMessages(messages)`; php: `BetaMcp::message($message)`; ruby: `Anthropic::Mcp.message(message)`) | Convertit les messages de prompt MCP au format de message de l'API Claude |
| `mcp_resource_to_content(resource)` (typescript: `mcpResourceToContent(resource)`; csharp: `BetaMcp.ResourceToContent(resource)`; go: `mcp.ResourceToBlock(resource)`; java: `BetaMcp.mcpResourceContents(resource)`; php: `BetaMcp::resourceToContent($resource)`; ruby: `Anthropic::Mcp.resource_to_contents(resource)`) | Convertit une ressource MCP en bloc de contenu de l'API Claude |
| `mcp_resource_to_file(resource)` (typescript: `mcpResourceToFile(resource)`; csharp: `BetaMcp.ResourceToFile(resource)`; go: `mcp.ResourceToFile(resource)`; java: `BetaMcp.mcpResourceFiles(resource)`; php: `BetaMcp::resourceToFile($resource)`; ruby: `Anthropic::Mcp.resource_to_files(resource)`) | Convertit une ressource MCP en objet fichier à téléverser |
### Utiliser les outils MCP
Convertissez les outils MCP pour les utiliser avec le [tool runner](https://platform.claude.com/docs/fr/agents-and-tools/tool-use/tool-runner) du SDK, qui gère automatiquement l'exécution des outils :
```python Python
from anthropic.lib.tools.mcp import async_mcp_tool
from mcp import ClientSession
from mcp.client.stdio import StdioServerParameters, stdio_client
client = AsyncAnthropic()
async def main() -> None:
# Se connecter à un serveur MCP
server_params = StdioServerParameters(command="mcp-server")
async with stdio_client(server_params) as (read, write):
async with ClientSession(read, write) as mcp_client:
await mcp_client.initialize()
# Lister les outils et les convertir pour l'API Claude
tools_result = await mcp_client.list_tools()
runner = client.beta.messages.tool_runner(
model="claude-opus-5-5",
max_tokens=1024,
messages=[
{"role": "user", "content": "What tools do you have available?"},
],
tools=[async_mcp_tool(tool, mcp_client) for tool in tools_result.tools],
)
final_message = await runner.until_done()
print(final_message)
asyncio.run(main())
```
```typescript TypeScript
import {
mcpTools,
type MCPCallToolResultLike,
type MCPClientLike
} 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();
// Se connecter à un serveur MCP
const transport = new StdioClientTransport({ command: "mcp-server", args: [] });
const mcpClient = new Client({ name: "my-client", version: "1.0.0" });
await mcpClient.connect(transport);
// Lister les outils et les convertir pour l'API Claude
const { tools } = await mcpClient.listTools();
// Le type de retour de callTool du SDK MCP inclut encore une forme de résultat héritée que
// mcpTools n'accepte pas ; on le restreint. À supprimer quand MCPClientLike s'élargira.
const mcpClientForTools: MCPClientLike = {
callTool: (params) => mcpClient.callTool(params) as Promise
};
const finalMessage = await anthropic.beta.messages.toolRunner({
model: "claude-opus-5-5",
max_tokens: 1024,
messages: [{ role: "user", content: "What tools do you have available?" }],
tools: mcpTools(tools, mcpClientForTools)
});
console.log(finalMessage);
```
```csharp C#
using Anthropic.Helpers.Beta;
using Anthropic.Helpers.Beta.Mcp;
using Anthropic.Models.Beta.Messages;
using ModelContextProtocol.Client;
using Messages = Anthropic.Models.Messages;
var anthropic = new AnthropicClient();
// Se connecter à un serveur MCP
await using var mcpClient = await McpClient.CreateAsync(
new StdioClientTransport(new StdioClientTransportOptions { Command = "mcp-server" })
);
// Lister les outils et les convertir pour l'API Claude
var tools = await BetaMcp.ListToolsAsync(mcpClient);
var runner = anthropic.Beta.Messages.ToolRunner(
new MessageCreateParams
{
Model = Messages::Model.ClaudeOpus5_5,
MaxTokens = 1024,
Messages =
[
new BetaMessageParam
{
Role = Role.User,
Content = "What tools do you have available?",
},
],
},
tools
);
var finalMessage = await runner.RunUntilDoneAsync();
Console.WriteLine(finalMessage);
```
```go Go
import (
// ...
// ...
"github.com/anthropics/anthropic-sdk-go/mcp"
mcpsdk "github.com/modelcontextprotocol/go-sdk/mcp"
)
func main() {
client := anthropic.NewClient()
ctx := context.Background()
// Se connecter à un serveur MCP
mcpClient := mcpsdk.NewClient(&mcpsdk.Implementation{Name: "my-client", Version: "1.0.0"}, nil)
session, err := mcpClient.Connect(ctx, &mcpsdk.CommandTransport{Command: exec.Command("mcp-server")}, nil)
if err != nil {
log.Fatal(err)
}
defer session.Close()
// Lister les outils et les convertir pour l'API Claude
toolsResult, err := session.ListTools(ctx, nil)
if err != nil {
log.Fatal(err)
}
betaTools, err := mcp.NewBetaTools(toolsResult.Tools, session)
if err != nil {
log.Fatal(err)
}
runner := client.Beta.Messages.NewToolRunner(betaTools, anthropic.BetaToolRunnerParams{
BetaMessageNewParams: anthropic.BetaMessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1024,
Messages: []anthropic.BetaMessageParam{
anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("What tools do you have available?")),
},
},
})
finalMessage, err := runner.RunToCompletion(ctx)
if err != nil {
log.Fatal(err)
}
fmt.Println(finalMessage.RawJSON())
}
```
```java Java
import com.anthropic.helpers.BetaToolRunner;
import com.anthropic.helpers.McpBetaTool;
import com.anthropic.mcp.BetaMcp;
import com.anthropic.models.beta.messages.BetaMessage;
import com.anthropic.models.beta.messages.MessageCreateParams;
import com.anthropic.models.messages.Model;
import io.modelcontextprotocol.client.McpClient;
import io.modelcontextprotocol.client.McpSyncClient;
import io.modelcontextprotocol.client.transport.ServerParameters;
import io.modelcontextprotocol.client.transport.StdioClientTransport;
import io.modelcontextprotocol.json.McpJsonDefaults;
import io.modelcontextprotocol.spec.McpSchema;
// ...
void main() throws Exception {
AnthropicClient anthropic = AnthropicOkHttpClient.fromEnv();
// Se connecter à un serveur MCP
StdioClientTransport transport = new StdioClientTransport(
ServerParameters.builder("mcp-server").build(), McpJsonDefaults.getMapper());
try (McpSyncClient mcpClient = McpClient.sync(transport)
.clientInfo(new McpSchema.Implementation("my-client", "1.0.0"))
.build()) {
mcpClient.initialize();
// Lister les outils et les convertir pour l'API Claude
List betaTools = BetaMcp.mcpTools(mcpClient.listTools().tools(), mcpClient);
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1024L)
.addUserMessage("What tools do you have available?")
.addTools(betaTools)
.build();
// Le runner produit un message par tour de l'assistant ; le dernier est la réponse finale
BetaToolRunner runner = anthropic.beta().messages().toolRunner(params);
BetaMessage finalMessage = null;
for (BetaMessage message : runner) {
finalMessage = message;
}
IO.println(finalMessage);
}
}
```
```php PHP
use Anthropic\Lib\Tools\BetaMcp;
use Mcp\Client;
use Mcp\Client\Transport\HttpTransport;
$anthropic = new Anthropic();
// Connexion à un serveur MCP. Le client MCP PHP se connecte via HTTP ; pointez ceci
// vers l'endpoint de votre serveur.
$mcp = Client::builder()->build();
$mcp->connect(new HttpTransport('http://localhost:8000/mcp'));
// Lister les outils et les convertir pour l'API Claude
$runner = $anthropic->beta->messages->toolRunner(
maxTokens: 1024,
messages: [['role' => 'user', 'content' => 'What tools do you have available?']],
model: 'claude-opus-5-5',
tools: BetaMcp::tools($mcp->listTools()->tools, $mcp),
);
echo $runner->runUntilDone(), "\n";
```
```ruby Ruby
require "mcp"
anthropic = Anthropic::Client.new
# Se connecter à un serveur MCP
transport = MCP::Client::Stdio.new(command: "mcp-server")
mcp_client = MCP::Client.new(transport: transport)
mcp_client.connect
# Lister les outils et les convertir pour l'API Claude
runner = anthropic.beta.messages.tool_runner(
model: "claude-opus-5-5",
max_tokens: 1024,
messages: [{ role: "user", content: "What tools do you have available?" }],
tools: Anthropic::Mcp.tools(mcp_client.tools, mcp_client)
)
final_message = runner.run_until_finished.last
puts final_message
```
### Utiliser les prompts MCP
Convertissez les messages de prompt MCP au format de message de l'API Claude :
```python Python
from anthropic.lib.tools.mcp import mcp_message
prompt = await mcp_client.get_prompt(name="my-prompt")
response = await client.beta.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
messages=[mcp_message(message) for message in prompt.messages],
)
print(response)
```
```typescript TypeScript
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-opus-5-5",
max_tokens: 1024,
messages: mcpMessages(messages)
});
console.log(response);
```
```csharp C#
var prompt = await mcpClient.GetPromptAsync("my-prompt");
var response = await anthropic.Beta.Messages.Create(
new MessageCreateParams
{
Model = Messages::Model.ClaudeOpus5_5,
MaxTokens = 1024,
Messages = BetaMcp.Messages(prompt.Messages),
}
);
Console.WriteLine(response);
```
```go Go
prompt, err := session.GetPrompt(ctx, &mcpsdk.GetPromptParams{Name: "my-prompt"})
if err != nil {
log.Fatal(err)
}
messages := make([]anthropic.BetaMessageParam, 0, len(prompt.Messages))
for _, promptMessage := range prompt.Messages {
message, err := mcp.ToMessage(promptMessage)
if err != nil {
log.Fatal(err)
}
messages = append(messages, message)
}
response, err := client.Beta.Messages.New(ctx, anthropic.BetaMessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1024,
Messages: messages,
})
if err != nil {
log.Fatal(err)
}
fmt.Println(response.RawJSON())
```
```java Java
McpSchema.GetPromptResult prompt = mcpClient.getPrompt(
new McpSchema.GetPromptRequest("my-prompt", Map.of()));
BetaMessage response = anthropic.beta().messages().create(MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1024L)
.messages(BetaMcp.mcpMessages(prompt.messages()))
.build());
IO.println(response);
```
```php PHP
$prompt = $mcp->getPrompt('my-prompt');
$response = $anthropic->beta->messages->create(
maxTokens: 1024,
messages: array_map(BetaMcp::message(...), $prompt->messages),
model: 'claude-opus-5-5',
);
echo $response, "\n";
```
```ruby Ruby
prompt = mcp_client.get_prompt(name: "my-prompt")
response = anthropic.beta.messages.create(
model: "claude-opus-5-5",
max_tokens: 1024,
messages: prompt["messages"].map { |message| Anthropic::Mcp.message(message) }
)
puts response
```
### Utiliser les ressources MCP
Convertissez les ressources MCP en blocs de contenu à inclure dans les messages, ou en objets fichier pour le téléversement :
```python Python
from anthropic.lib.tools.mcp import (
mcp_resource_to_content,
mcp_resource_to_file,
)
# En tant que bloc de contenu dans un message
resource = await mcp_client.read_resource(uri="file:///path/to/doc.txt")
response = await client.beta.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
messages=[
{
"role": "user",
"content": [
mcp_resource_to_content(resource),
{"type": "text", "text": "Summarize this document"},
],
}
],
)
print(response)
# En tant que téléversement de fichier
file_resource = await mcp_client.read_resource(
uri="file:///path/to/data.json",
)
uploaded = await client.files.upload(
file=mcp_resource_to_file(file_resource),
)
print(uploaded.id)
```
```typescript TypeScript
import { mcpResourceToContent, mcpResourceToFile } from "@anthropic-ai/sdk/helpers/beta/mcp";
// En tant que bloc de contenu dans un message
const resource = await mcpClient.readResource({ uri: "file:///path/to/doc.txt" });
const response = await anthropic.beta.messages.create({
model: "claude-opus-5-5",
max_tokens: 1024,
messages: [
{
role: "user",
content: [
mcpResourceToContent(resource),
{ type: "text", text: "Summarize this document" }
]
}
]
});
console.log(response);
// En tant que téléversement de fichier
const fileResource = await mcpClient.readResource({ uri: "file:///path/to/data.json" });
const uploaded = await anthropic.files.upload({ file: mcpResourceToFile(fileResource) });
console.log(uploaded.id);
```
```csharp C#
// En tant que bloc de contenu dans un message
var resource = await mcpClient.ReadResourceAsync("file:///path/to/doc.txt");
var response = await anthropic.Beta.Messages.Create(
new MessageCreateParams
{
Model = Messages::Model.ClaudeOpus5_5,
MaxTokens = 1024,
Messages =
[
new BetaMessageParam
{
Role = Role.User,
Content = new BetaMessageParamContent(
[
BetaMcp.ResourceToContent(resource),
new BetaTextBlockParam { Text = "Summarize this document" },
]
),
},
],
}
);
Console.WriteLine(response);
// En tant que téléversement de fichier
var fileResource = await mcpClient.ReadResourceAsync("file:///path/to/data.json");
var (filename, data, mediaType) = BetaMcp.ResourceToFile(fileResource);
// Construisez explicitement la partie fichier afin que le nom de fichier et le type MIME de la ressource
// soient transmis lors du téléversement.
var file = new BinaryContent { Stream = new MemoryStream(data), FileName = filename };
if (mediaType is not null)
{
file.ContentType = new(mediaType);
}
var uploaded = await anthropic.Files.Upload(new FileUploadParams { File = file });
Console.WriteLine(uploaded.ID);
```
```go Go
// En tant que bloc de contenu dans un message
resource, err := session.ReadResource(ctx, &mcpsdk.ReadResourceParams{URI: "file:///path/to/doc.txt"})
if err != nil {
log.Fatal(err)
}
block, err := mcp.ResourceToBlock(resource)
if err != nil {
log.Fatal(err)
}
response, err := client.Beta.Messages.New(ctx, anthropic.BetaMessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1024,
Messages: []anthropic.BetaMessageParam{
anthropic.NewBetaUserMessage(
// ResourceToBlock renvoie l'union de contenu tool-result ; le contenu
// de message est un type union distinct, donc on ré-encapsule les variantes partagées
// (mcp.ToMessage fait de même en interne).
anthropic.BetaContentBlockParamUnion{
OfText: block.OfText,
OfImage: block.OfImage,
OfDocument: block.OfDocument,
},
anthropic.NewBetaTextBlock("Summarize this document"),
),
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(response.RawJSON())
// En tant que téléversement de fichier
fileResult, err := session.ReadResource(ctx, &mcpsdk.ReadResourceParams{URI: "file:///path/to/data.json"})
if err != nil {
log.Fatal(err)
}
fileReader, err := mcp.ResourceToFile(fileResult)
if err != nil {
log.Fatal(err)
}
uploaded, err := client.Files.Upload(ctx, anthropic.FileUploadParams{File: fileReader})
if err != nil {
log.Fatal(err)
}
fmt.Println(uploaded.ID)
```
```java Java
// En tant que bloc de contenu dans un message
McpSchema.ReadResourceResult resource = mcpClient.readResource(
new McpSchema.ReadResourceRequest("file:///path/to/doc.txt"));
List content =
new ArrayList<>(BetaMcp.mcpResourceContents(resource));
content.add(BetaContentBlockParam.ofText(
BetaTextBlockParam.builder().text("Summarize this document").build()));
BetaMessage response = anthropic.beta().messages().create(MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1024L)
.addUserMessageOfBetaContentBlockParams(content)
.build());
IO.println(response);
// En tant que téléversement de fichier
McpSchema.ReadResourceResult fileResource = mcpClient.readResource(
new McpSchema.ReadResourceRequest("file:///path/to/data.json"));
McpResourceFile resourceFile = BetaMcp.mcpResourceFiles(fileResource).getFirst();
// Construire explicitement la partie fichier afin que le nom de fichier et le type MIME de la ressource
// soient transmis au téléversement.
MultipartField.Builder fileField = MultipartField.builder()
.value(new ByteArrayInputStream(resourceFile.content()))
.filename(resourceFile.filename());
if (resourceFile.mimeType() != null) {
fileField.contentType(resourceFile.mimeType());
}
var uploaded = anthropic.files().upload(FileUploadParams.builder()
.file(fileField.build())
.build());
IO.println(uploaded.id());
```
```php PHP
// En tant que bloc de contenu dans un message
$resource = $mcp->readResource('file:///path/to/doc.txt');
$response = $anthropic->beta->messages->create(
maxTokens: 1024,
messages: [
[
'role' => 'user',
'content' => [
BetaMcp::resourceToContent($resource),
['type' => 'text', 'text' => 'Summarize this document'],
],
],
],
model: 'claude-opus-5-5',
);
echo $response, "\n";
// En tant que téléversement de fichier
$fileResource = $mcp->readResource('file:///path/to/data.json');
$file = $anthropic->files->upload(file: BetaMcp::resourceToFile($fileResource));
echo $file->id, "\n";
```
```ruby Ruby
# En tant que bloc de contenu dans un message
resource = mcp_client.read_resource(uri: "file:///path/to/doc.txt")
response = anthropic.beta.messages.create(
model: "claude-opus-5-5",
max_tokens: 1024,
messages: [
{
role: "user",
content: [
*Anthropic::Mcp.resource_to_contents(resource),
{ type: "text", text: "Summarize this document" }
]
}
]
)
puts response
# En tant que téléversement de fichier
file_resource = mcp_client.read_resource(uri: "file:///path/to/data.json")
file = Anthropic::Mcp.resource_to_files(file_resource).first
uploaded_file = anthropic.files.upload(file: file)
puts uploaded_file.id
```
### Gestion des erreurs
Les fonctions de conversion échouent avec `UnsupportedMCPValueError` (go: `UnsupportedValueError`; java, csharp: `AnthropicInvalidDataException`) si une valeur MCP n'est pas prise en charge par l'API Claude (levée comme exception, ou renvoyée comme erreur en Go). Cela peut se produire avec des types de contenu, des types MIME ou des liens de ressources non pris en charge (résolvez les liens de ressources avec votre client MCP avant la conversion).
## Requêtes par lots
Vous pouvez inclure `mcp_servers` dans les requêtes de l'[API Message Batches](https://platform.claude.com/docs/fr/build-with-claude/batch-processing). Les appels d'outils MCP via l'API Batches sont facturés au même tarif que ceux des requêtes classiques de l'API Messages.
## Conservation des données
Le connecteur MCP n'est pas couvert par les accords 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'éligibilité ZDR de toutes les fonctionnalités, consultez [API et conservation des données](https://platform.claude.com/docs/fr/manage-claude/api-and-data-retention).
## 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 :** 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 désormais 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 l'allowlist, la denylist et la configuration par outil
### Étapes de migration
**Avant (déprécié) :**
```json
{
"model": "claude-opus-5-5",
"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) :**
```json
{
"model": "claude-opus-5-5",
"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
| Ancien modèle | Nouveau modèle |
| ----------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| Pas de `tool_configuration` (tous les outils activés) | MCPToolset sans `default_config` ni `configs` |
| `tool_configuration.enabled: false` | MCPToolset avec `default_config.enabled: false` |
| `tool_configuration.allowed_tools: [...]` | MCPToolset avec `default_config.enabled: false` et des outils spécifiques activés dans `configs` |
## Version dépréciée : mcp-client-2025-04-04
Cette version est dépréciée. Migrez vers `mcp-client-2025-11-20` à l'aide du [guide de migration](https://platform.claude.com/docs/fr/agents-and-tools/mcp-connector#migration-guide) ci-dessus.
La version précédente du connecteur MCP incluait la configuration des outils directement dans la définition du serveur MCP :
```json
{
"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"]
}
}
]
}
```
### Description des champs dépréciés
| Propriété | Type | Description |
| ---------------------------------- | ------- | ---------------------------------------------------------------------------- |
| `tool_configuration` | object | **Déprécié :** utilisez MCPToolset dans le tableau `tools` à la place |
| `tool_configuration.enabled` | boolean | **Déprécié :** utilisez `default_config.enabled` dans MCPToolset |
| `tool_configuration.allowed_tools` | array | **Déprécié :** utilisez le modèle d'allowlist avec `configs` dans MCPToolset |