---
title: Connettore MCP
url: https://platform.claude.com/docs/it/agents-and-tools/mcp-connector
description: Connettiti a server MCP remoti direttamente dalla Messages API senza un client MCP, e crea allowlist, denylist o configura singoli strumenti.
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 funzionalità connettore "Model Context Protocol", o MCP, di Claude ti consente di connetterti a server MCP remoti direttamente dalla Messages API senza un client MCP separato.
La versione precedente di questa funzionalità (`mcp-client-2025-04-04`) è deprecata. Consulta [Versione deprecata: mcp-client-2025-04-04](https://platform.claude.com/docs/it/agents-and-tools/mcp-connector#deprecated-version-mcp-client-2025-04-04).
## Caratteristiche principali
* **Integrazione diretta con l'API:** Connettiti ai server MCP senza implementare un client MCP
* **Supporto per la chiamata di strumenti:** Accedi agli strumenti MCP tramite la Messages API
* **Configurazione flessibile degli strumenti:** Abilita tutti gli strumenti, inserisci in allowlist strumenti specifici o in denylist gli strumenti indesiderati
* **Configurazione per singolo strumento:** Configura singoli strumenti con impostazioni personalizzate
* **Autenticazione OAuth:** Supporto per token Bearer OAuth per server autenticati
* **Server multipli:** Connettiti a più server MCP in una singola richiesta
## Quando Claude usa gli strumenti MCP
Una volta connesso un server MCP, Claude chiama i suoi strumenti quando la richiesta dell'utente corrisponde alla capacità descritta di uno strumento, sia esplicitamente ("cerca in Jira i bug aperti") sia implicitamente ("cosa sta bloccando il rilascio?" con un server Jira collegato).
Claude **non** chiama uno strumento MCP per domande di conoscenza generale su un servizio connesso. Chiedere "come funzionano i database di Notion?" con un server Notion collegato riceve una risposta diretta; chiedere "cosa c'è nel mio database Projects?" attiva lo strumento.
Puoi orientare la propensione di Claude a chiamare gli strumenti MCP tramite il tuo "system prompt" (prompt di sistema). Consulta [Quando Claude usa gli strumenti](https://platform.claude.com/docs/it/agents-and-tools/tool-use/overview#when-claude-uses-tools) per indicazioni generali ed esempi di formulazione.
## Limitazioni
* Dell'insieme di funzionalità della [specifica MCP](https://modelcontextprotocol.io/introduction#explore-mcp), attualmente sono supportate solo le [chiamate di strumenti](https://modelcontextprotocol.io/docs/concepts/tools).
* Il server deve essere esposto pubblicamente tramite HTTP (supporta sia il trasporto Streamable HTTP sia SSE). I server STDIO locali non possono essere connessi direttamente.
## Utilizzo del connettore MCP nella Messages API
Il connettore MCP utilizza due componenti:
1. **Definizione del server MCP** (array `mcp_servers`): Definisce i dettagli di connessione al server (URL, autenticazione)
2. **Toolset MCP** (array `tools`): Configura quali strumenti abilitare e come configurarli
### Esempio di base
Questo esempio abilita tutti gli strumenti di un server MCP con la configurazione predefinita:
```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
```
## Configurazione del server MCP
Ogni server MCP nell'array `mcp_servers` definisce i dettagli di connessione:
```json
{
"type": "url",
"url": "https://example-server.modelcontextprotocol.io/sse",
"name": "example-mcp",
"authorization_token": "YOUR_TOKEN"
}
```
### Descrizione dei campi
| Proprietà | Tipo | Obbligatorio | Descrizione |
| --------------------- | ------ | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | string | Sì | Attualmente è supportato solo "url". |
| `url` | string | Sì | L'URL del server MCP. Deve iniziare con https\://. |
| `name` | string | Sì | Un identificatore univoco per questo server MCP. Deve essere referenziato da esattamente un MCPToolset nell'array `tools`. |
| `authorization_token` | string | No | Token di autorizzazione OAuth se richiesto dal server MCP. Consulta [Autenticazione](https://platform.claude.com/docs/it/agents-and-tools/mcp-connector#authentication) per sapere come ottenerne uno, oppure la [specifica MCP](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization) per i dettagli del protocollo. |
## Configurazione del toolset MCP
L'MCPToolset si trova nell'array `tools` e configura quali strumenti del server MCP sono abilitati e come devono essere configurati.
### Struttura di 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
}
}
}
```
### Descrizione dei campi
| Proprietà | Tipo | Obbligatorio | Descrizione |
| ----------------- | ------ | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | string | Sì | Deve essere "mcp\_toolset". |
| `mcp_server_name` | string | Sì | Deve corrispondere al nome di un server definito nell'array `mcp_servers`. |
| `default_config` | object | No | Configurazione predefinita applicata a tutti gli strumenti di questo set. Le configurazioni dei singoli strumenti in `configs` sovrascrivono questi valori predefiniti. |
| `configs` | object | No | Sovrascritture della configurazione per singolo strumento. Le chiavi sono i nomi degli strumenti, i valori sono oggetti di configurazione. |
| `cache_control` | object | No | Configurazione del breakpoint di cache della [cache dei prompt](https://platform.claude.com/docs/it/build-with-claude/prompt-caching) per questo toolset. |
Con l'header beta `mcp-client-2026-09-15`, un MCPToolset accetta anche `tools`, una copia fissata dell'elenco degli strumenti del server. Consulta [Fissa l'elenco degli strumenti di un server MCP](https://platform.claude.com/docs/it/agents-and-tools/mcp-connector#pin-mcp-tool-list).
### Opzioni di configurazione degli strumenti
Ogni strumento (sia configurato in `default_config` sia in `configs`) supporta i seguenti campi:
| Proprietà | Tipo | Predefinito | Descrizione |
| --------------- | ------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `enabled` | boolean | `true` | Indica se questo strumento è abilitato. |
| `defer_loading` | boolean | `false` | Se true, la descrizione dello strumento non viene inviata inizialmente al modello. Usato con lo [strumento di ricerca strumenti](https://platform.claude.com/docs/it/agents-and-tools/tool-use/tool-search-tool). |
Per l'elenco completo degli strumenti forniti da Anthropic e delle proprietà opzionali come `defer_loading`, consulta il [Riferimento degli strumenti](https://platform.claude.com/docs/it/agents-and-tools/tool-use/tool-reference). Per cercare all'interno di grandi insiemi di strumenti, consulta lo [strumento di ricerca strumenti](https://platform.claude.com/docs/it/agents-and-tools/tool-use/tool-search-tool).
### Unione delle configurazioni
I valori di configurazione vengono uniti con questa precedenza (dalla più alta alla più bassa):
1. Impostazioni specifiche dello strumento in `configs`
2. `default_config` a livello di set
3. Valori predefiniti di sistema
Esempio:
```json
{
"type": "mcp_toolset",
"mcp_server_name": "google-calendar-mcp",
"default_config": {
"defer_loading": true
},
"configs": {
"search_events": {
"enabled": false
}
}
}
```
Risulta in:
* `search_events`: `enabled: false` (da configs), `defer_loading: true` (da default\_config)
* Tutti gli altri strumenti: `enabled: true` (predefinito di sistema), `defer_loading: true` (da default\_config)
## Pattern di configurazione comuni
### Abilitare tutti gli strumenti con la configurazione predefinita
Il pattern più semplice: abilita tutti gli strumenti di un server:
```json
{
"type": "mcp_toolset",
"mcp_server_name": "google-calendar-mcp"
}
```
### Allowlist: abilitare solo strumenti specifici
Imposta `enabled: false` come predefinito, quindi abilita esplicitamente strumenti specifici:
```json
{
"type": "mcp_toolset",
"mcp_server_name": "google-calendar-mcp",
"default_config": {
"enabled": false
},
"configs": {
"search_events": {
"enabled": true
},
"create_event": {
"enabled": true
}
}
}
```
### Denylist: disabilitare strumenti specifici
Abilita tutti gli strumenti per impostazione predefinita, quindi disabilita esplicitamente gli strumenti indesiderati. Inserire in denylist gli strumenti di scrittura o distruttivi è consigliato quando si creano assistenti di sola lettura, o quando si desidera un passaggio di conferma umana prima delle modifiche di stato:
```json
{
"type": "mcp_toolset",
"mcp_server_name": "google-calendar-mcp",
"configs": {
"delete_all_events": {
"enabled": false
},
"share_calendar_publicly": {
"enabled": false
}
}
}
```
### Misto: allowlist con configurazione per singolo strumento
Combina l'allowlist con una configurazione personalizzata per ogni strumento:
```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
}
}
}
```
In questo esempio:
* `search_events` è abilitato con `defer_loading: false`
* `list_events` è abilitato con `defer_loading: true` (ereditato da default\_config)
* Tutti gli altri strumenti sono disabilitati
## Regole di validazione
L'API applica queste regole di validazione:
* **Il server deve esistere:** Il `mcp_server_name` in un MCPToolset deve corrispondere a un server definito nell'array `mcp_servers`
* **Il server deve essere utilizzato:** Ogni server MCP definito in `mcp_servers` deve essere referenziato da esattamente un MCPToolset
* **Toolset univoco per server:** Ogni server MCP può essere referenziato da un solo MCPToolset
* **Nomi di strumenti sconosciuti:** Se un nome di strumento in `configs` non esiste sul server MCP, viene registrato un avviso nel backend ma non viene restituito alcun errore (i server MCP possono avere disponibilità dinamica degli strumenti)
## Tipi di contenuto della risposta
Quando Claude usa gli strumenti MCP, la risposta include due nuovi tipi di blocchi di contenuto:
### Blocco MCP tool use
```json
{
"type": "mcp_tool_use",
"id": "mcptoolu_014Q35RayjACSWkSj4X2yov1",
"name": "echo",
"server_name": "example-mcp",
"input": { "param1": "value1", "param2": "value2" }
}
```
### Blocco MCP tool result
```json
{
"type": "mcp_tool_result",
"tool_use_id": "mcptoolu_014Q35RayjACSWkSj4X2yov1",
"is_error": false,
"content": [
{
"type": "text",
"text": "Hello"
}
]
}
```
## Fissa l'elenco degli strumenti di un server MCP (beta)
Un server MCP può modificare i propri strumenti in qualsiasi momento. L'header beta `mcp-client-2026-09-15` registra l'elenco degli strumenti restituito da ciascun server e ti consente di fissarlo, in modo che un server che modifica i propri strumenti non cambi ciò che Claude vede a metà di una conversazione. Include tutto ciò che include `mcp-client-2025-11-20`, quindi invialo al posto di quell'header. È disponibile sulla Claude API.
Quando l'API chiede a un server MCP i suoi strumenti durante la produzione di una risposta, la risposta inizia con un blocco `mcp_tool_listing` per quel server, un blocco per ciascun server interrogato:
```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"]
}
}
]
}
```
Se il tuo codice legge `content[0]`, salta questi blocchi. Rinvia il messaggio dell'assistente invariato, blocchi `mcp_tool_listing` inclusi, e continua a inviare `mcp-client-2026-09-15` in ogni richiesta che ne contiene uno. Le richieste successive useranno quindi l'elenco registrato per quel server invece di interrogarlo di nuovo.
Per fissare tu stesso un elenco, copia il campo `tools` di un blocco nel campo `tools` dell'MCPToolset di quel server. L'API quindi non chiede al server i suoi strumenti, e gli strumenti del toolset sono esattamente quelle voci, con `default_config` e `configs` applicati:
```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"]
}
}
]
}
```
Ogni voce in `tools` contiene il `name` dello strumento così come il server lo elenca (senza il nome del server), la sua `description` e il suo `input_schema`.
L'esempio seguente invia una richiesta con un toolset non fissato, copia l'elenco restituito nel campo `tools` del toolset e invia di nuovo la richiesta. La seconda risposta non contiene alcun blocco `mcp_tool_listing`, perché l'API non interroga il server:
```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?"
}
]
}'
# Prima richiesta: il toolset non è fissato, quindi l'API chiede al server i suoi
# strumenti e la risposta inizia con un blocco mcp_tool_listing.
# tee mostra la risposta su stderr mentre la variabile la cattura.
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)
# Fissa l'elenco: copia gli strumenti del blocco nel toolset. L'API usa
# esattamente queste voci e non interroga di nuovo il server.
TOOLS=$(jq '.content[] | select(.type == "mcp_tool_listing") | .tools' \
<<<"$FIRST")
PINNED=$(jq --argjson tools "$TOOLS" '.tools[0].tools = $tools' <<<"$BODY")
# Con un toolset fissato, la risposta non contiene alcun blocco 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
)
# Prima richiesta: il toolset non è fissato, quindi l'API chiede al server i
# suoi strumenti e la risposta inizia con un blocco mcp_tool_listing.
# tee mostra la risposta su stderr mentre la variabile la cattura.
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")
# Fissa l'elenco: copia gli strumenti del blocco nel toolset. Il flag --tool
# sostituisce l'array tools del body. L'API usa esattamente queste voci e
# non interroga di nuovo il server, quindi la risposta non ha il blocco 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?"},
]
# Prima richiesta: il toolset non è fissato, quindi l'API chiede al server
# i suoi strumenti e la risposta inizia con un blocco 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])
# Fissa l'elenco: copia gli strumenti del blocco nel toolset. L'API usa
# esattamente queste voci e non interroga di nuovo il server.
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,
)
# Con un toolset fissato, la risposta non contiene alcun blocco 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?" }
];
// Prima richiesta: il toolset non è fissato, quindi l'API chiede al server
// i suoi strumenti e la risposta inizia con un blocco 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));
// Fissa l'elenco: copia gli strumenti del blocco nel toolset. L'API usa
// esattamente queste voci e non interroga di nuovo il server.
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
});
// Con un toolset fissato, la risposta non contiene alcun blocco 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?" },
];
// Prima richiesta: il toolset non è fissato, quindi l'API chiede al server
// i suoi strumenti e la risposta inizia con un blocco 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)));
// Fissa l'elenco: copia gli strumenti del blocco nel toolset. L'API usa
// esattamente queste voci e non interroga di nuovo il server.
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,
});
// Con un toolset fissato, la risposta non contiene alcun blocco 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?")),
}
// Prima richiesta: il toolset non è fissato, quindi l'API chiede al server
// i suoi strumenti e la risposta inizia con un blocco 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
}
}
// Fissa l'elenco: copia gli strumenti del blocco nel toolset. L'API usa
// esattamente queste voci e non interroga di nuovo il server.
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)
}
// Con un toolset fissato, la risposta non contiene alcun blocco 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();
// Prima richiesta: il toolset non è fissato, quindi l'API chiede al server
// i suoi strumenti e la risposta inizia con un blocco 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());
// Fissa l'elenco: copia gli strumenti del blocco nel toolset. L'API usa
// esattamente queste voci e non interroga di nuovo il server.
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());
// Con un toolset fissato, la risposta non contiene alcun blocco 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?']];
// Prima richiesta: il toolset non è fissato, quindi l'API chiede al server
// i suoi strumenti e la risposta inizia con un blocco 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;
// Fissa l'elenco: copia gli strumenti del blocco nel toolset. L'API usa
// esattamente queste voci e non interroga di nuovo il server.
$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,
);
// Con un toolset fissato, la risposta non contiene alcun blocco 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?" }]
# Prima richiesta: il toolset non è fissato, quindi l'API chiede al server
# i suoi strumenti e la risposta inizia con un blocco 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
# Fissa l'elenco: copia gli strumenti del blocco nel toolset. L'API usa
# esattamente queste voci e non interroga di nuovo il server.
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:
)
# Con un toolset fissato, la risposta non contiene alcun blocco mcp_tool_listing.
puts second.content.map(&:type).inspect
```
Aggiungendo anche l'header beta `inline-tools-2026-09-15`, puoi aggiungere un server MCP a metà di una conversazione. Consulta [Aggiungere un server MCP a metà conversazione](https://platform.claude.com/docs/it/build-with-claude/mid-conversation-system-messages#add-an-mcp-server-mid-conversation-beta).
## Server MCP multipli
Puoi connetterti a più server MCP includendo più definizioni di server in `mcp_servers` e un MCPToolset corrispondente per ciascuno nell'array `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
}
}
]
}
```
Con molti strumenti disponibili, Claude seleziona in base ai nomi e alle descrizioni degli strumenti. Descrizioni degli strumenti chiare e specifiche migliorano l'accuratezza della selezione. Per grandi insiemi di strumenti (decine di strumenti su diversi server), considera di abilitare [`defer_loading`](https://platform.claude.com/docs/it/agents-and-tools/mcp-connector#tool-configuration-options) con lo [strumento di ricerca strumenti](https://platform.claude.com/docs/it/agents-and-tools/tool-use/tool-search-tool) in modo che per ogni query vengano presentati solo gli strumenti pertinenti.
## Autenticazione
Per i server MCP che richiedono l'autenticazione OAuth, dovrai ottenere un token di accesso. La beta del connettore MCP supporta il passaggio di un parametro `authorization_token` nella definizione del server MCP. Ci si aspetta che i consumatori dell'API gestiscano il flusso OAuth e ottengano il token di accesso prima di effettuare la chiamata API, e che aggiornino il token secondo necessità.
### Ottenere un token di accesso per i test
L'MCP inspector può guidarti attraverso il processo di ottenimento di un token di accesso a scopo di test.
1. Esegui l'inspector con il seguente comando. È necessario avere Node.js installato sulla tua macchina.
```bash
npx @modelcontextprotocol/inspector
```
2. Nella barra laterale a sinistra, per **Transport type**, seleziona **SSE** oppure **Streamable HTTP**.
3. Inserisci l'URL del server MCP.
4. Nell'area a destra, fai clic su **Open Auth Settings** dopo **Need to configure authentication?**.
5. Fai clic su **Quick OAuth Flow** e autorizza nella schermata OAuth.
6. Segui i passaggi nella sezione **OAuth Flow Progress** dell'inspector e fai clic su **Continue** fino a raggiungere **Authentication complete**.
7. Copia il valore di `access_token`.
8. Incollalo nel campo `authorization_token` della configurazione del tuo server MCP.
### Utilizzo del token di accesso
Una volta ottenuto un token di accesso utilizzando uno dei flussi OAuth precedenti, puoi usarlo nella configurazione del tuo server MCP:
```json
{
"mcp_servers": [
{
"type": "url",
"url": "https://example-server.modelcontextprotocol.io/sse",
"name": "authenticated-server",
"authorization_token": "YOUR_ACCESS_TOKEN_HERE"
}
]
}
```
Per spiegazioni dettagliate del flusso OAuth, fai riferimento alla [sezione Authorization](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization) nella specifica MCP.
## Helper MCP lato client
Se gestisci autonomamente la connessione del client MCP (ad esempio, con server stdio locali, prompt MCP o risorse MCP), l'SDK fornisce funzioni helper che convertono tra i tipi MCP e i tipi della Claude API. Questo elimina il codice di conversione manuale quando usi un SDK MCP per il tuo linguaggio (ad esempio, il [TypeScript MCP SDK](https://github.com/modelcontextprotocol/typescript-sdk)) insieme all'SDK di Anthropic.
Usa il [parametro API `mcp_servers`](https://platform.claude.com/docs/it/agents-and-tools/mcp-connector#using-the-mcp-connector-in-the-messages-api) quando hai server remoti accessibili tramite URL e ti serve solo il supporto per gli strumenti. Usa gli helper lato client quando ti servono server locali, prompt, risorse o un maggiore controllo sulla connessione con l'SDK di base.
### Installazione
Installa sia l'SDK di Anthropic sia l'SDK MCP:
Gli helper MCP sono inclusi nell'extra `mcp`, che richiede Python 3.10 o successivo:
```bash
pip install "anthropic[mcp]"
```
```bash
npm install @anthropic-ai/sdk @modelcontextprotocol/sdk
```
Gli helper si trovano nel pacchetto separato `Anthropic.Mcp`; il client MCP stesso proviene dal [pacchetto ufficiale ModelContextProtocol](https://www.nuget.org/packages/ModelContextProtocol):
```bash
dotnet add package Anthropic.Mcp
dotnet add package ModelContextProtocol
```
Gli helper si trovano nel sottopacchetto `mcp` dell'SDK Go, che si basa sul [MCP Go SDK](https://github.com/modelcontextprotocol/go-sdk):
```bash
go get github.com/anthropics/anthropic-sdk-go/mcp
```
Gli helper si trovano nell'artefatto separato `anthropic-java-mcp`, che richiede Java 17 o successivo (l'SDK di base supporta Java 8). Aggiungilo insieme alla dipendenza di 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
```
Gli helper usano l'[MCP PHP SDK](https://packagist.org/packages/mcp/sdk) ufficiale:
```bash
composer require "anthropic-ai/sdk" "guzzlehttp/guzzle:^7" "mcp/sdk"
```
Gli helper usano la [gem `mcp`](https://rubygems.org/gems/mcp) ufficiale:
```bash
bundle add anthropic mcp
```
### Helper disponibili
Importa gli helper per il tuo linguaggio:
```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"
# Gli helper sono esposti nel modulo Anthropic::Mcp
```
| Helper | Descrizione |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `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)`) | Converte gli strumenti MCP in strumenti della Claude API da usare con `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)`) | Converte i messaggi dei prompt MCP nel formato dei messaggi della Claude API |
| `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)`) | Converte una risorsa MCP in un blocco di contenuto della Claude API |
| `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)`) | Converte una risorsa MCP in un oggetto file da caricare |
### Usare gli strumenti MCP
Converti gli strumenti MCP per usarli con il [tool runner](https://platform.claude.com/docs/it/agents-and-tools/tool-use/tool-runner) dell'SDK, che gestisce automaticamente l'esecuzione degli strumenti:
```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:
# Connettiti a un server 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()
# Elenca gli strumenti e convertili per l'API di 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();
// Connettiti a un server MCP
const transport = new StdioClientTransport({ command: "mcp-server", args: [] });
const mcpClient = new Client({ name: "my-client", version: "1.0.0" });
await mcpClient.connect(transport);
// Elenca gli strumenti e convertili per l'API Claude
const { tools } = await mcpClient.listTools();
// Il tipo di ritorno di callTool dell'SDK MCP include ancora una forma di risultato legacy che
// mcpTools non accetta; restringilo. Rimuovi questo quando MCPClientLike verrà ampliato.
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();
// Connettiti a un server MCP
await using var mcpClient = await McpClient.CreateAsync(
new StdioClientTransport(new StdioClientTransportOptions { Command = "mcp-server" })
);
// Elenca gli strumenti e convertili per 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()
// Connettiti a un server 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()
// Elenca gli strumenti e convertili per 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();
// Connettiti a un server 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();
// Elenca gli strumenti e convertili per l'API di 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();
// Il runner produce un messaggio per ogni turno dell'assistente; l'ultimo è la risposta 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();
// Connettiti a un server MCP. Il client MCP PHP si connette via HTTP; punta questo
// all'endpoint del tuo server.
$mcp = Client::builder()->build();
$mcp->connect(new HttpTransport('http://localhost:8000/mcp'));
// Elenca gli strumenti e convertili per 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
# Connettiti a un server MCP
transport = MCP::Client::Stdio.new(command: "mcp-server")
mcp_client = MCP::Client.new(transport: transport)
mcp_client.connect
# Elenca gli strumenti e convertili per 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
```
### Usare i prompt MCP
Converti i messaggi dei prompt MCP nel formato messaggio della Claude API:
```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
```
### Usare le risorse MCP
Converti le risorse MCP in blocchi di contenuto da includere nei messaggi, oppure in oggetti file per il caricamento:
```python Python
from anthropic.lib.tools.mcp import (
mcp_resource_to_content,
mcp_resource_to_file,
)
# Come blocco di contenuto in un messaggio
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)
# Come caricamento di file
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";
// Come blocco di contenuto in un messaggio
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);
// Come caricamento di file
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#
// Come blocco di contenuto in un messaggio
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);
// Come caricamento di file
var fileResource = await mcpClient.ReadResourceAsync("file:///path/to/data.json");
var (filename, data, mediaType) = BetaMcp.ResourceToFile(fileResource);
// Costruisci esplicitamente la parte file in modo che il nome file e il tipo MIME della risorsa
// vengano mantenuti nel caricamento.
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
// Come blocco di contenuto in un messaggio
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 restituisce l'unione di contenuto tool-result; il contenuto
// del messaggio è un tipo unione separato, quindi riavvolgi le varianti condivise
// (mcp.ToMessage fa lo stesso internamente).
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())
// Come caricamento di file
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
// Come blocco di contenuto in un messaggio
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);
// Come caricamento di file
McpSchema.ReadResourceResult fileResource = mcpClient.readResource(
new McpSchema.ReadResourceRequest("file:///path/to/data.json"));
McpResourceFile resourceFile = BetaMcp.mcpResourceFiles(fileResource).getFirst();
// Costruisci esplicitamente la parte file in modo che il nome file e il tipo MIME della risorsa
// vengano mantenuti nel caricamento.
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
// Come blocco di contenuto in un messaggio
$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";
// Come caricamento di file
$fileResource = $mcp->readResource('file:///path/to/data.json');
$file = $anthropic->files->upload(file: BetaMcp::resourceToFile($fileResource));
echo $file->id, "\n";
```
```ruby Ruby
# Come blocco di contenuto in un messaggio
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
# Come caricamento di file
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
```
### Gestione degli errori
Le funzioni di conversione falliscono con `UnsupportedMCPValueError` (go: `UnsupportedValueError`; java, csharp: `AnthropicInvalidDataException`) se un valore MCP non è supportato dalla Claude API (l'errore viene lanciato oppure, in Go, restituito come errore). Questo può accadere con tipi di contenuto, tipi MIME o link a risorse non supportati (risolvi i link a risorse con il tuo client MCP prima della conversione).
## Richieste batch
Puoi includere `mcp_servers` nelle richieste della [Message Batches API](https://platform.claude.com/docs/it/build-with-claude/batch-processing). Le chiamate di strumenti MCP tramite la Batches API hanno lo stesso prezzo di quelle nelle normali richieste della Messages API.
## Conservazione dei dati
Il connettore MCP non è coperto dagli accordi ZDR. I dati scambiati con i server MCP, incluse le definizioni degli strumenti e i risultati di esecuzione, vengono conservati secondo la politica standard di conservazione dei dati di Anthropic.
Per l'idoneità ZDR di tutte le funzionalità, consulta [API e conservazione dei dati](https://platform.claude.com/docs/it/manage-claude/api-and-data-retention).
## Guida alla migrazione
Se stai utilizzando l'header beta deprecato `mcp-client-2025-04-04`, segui questa guida per migrare alla nuova versione.
### Modifiche principali
1. **Nuovo header beta:** Passa da `mcp-client-2025-04-04` a `mcp-client-2025-11-20`
2. **Configurazione degli strumenti spostata:** La configurazione degli strumenti ora si trova nell'array `tools` come oggetti MCPToolset, non nella definizione del server MCP
3. **Configurazione più flessibile:** Il nuovo pattern supporta allowlist, denylist e configurazione per singolo strumento
### Passaggi di migrazione
**Prima (deprecato):**
```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"]
}
}
]
}
```
**Dopo (attuale):**
```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
}
}
}
]
}
```
### Pattern di migrazione comuni
| Vecchio pattern | Nuovo pattern |
| ------------------------------------------------------------ | ------------------------------------------------------------------------------------------- |
| Nessuna `tool_configuration` (tutti gli strumenti abilitati) | MCPToolset senza `default_config` né `configs` |
| `tool_configuration.enabled: false` | MCPToolset con `default_config.enabled: false` |
| `tool_configuration.allowed_tools: [...]` | MCPToolset con `default_config.enabled: false` e strumenti specifici abilitati in `configs` |
## Versione deprecata: mcp-client-2025-04-04
Questa versione è deprecata. Migra a `mcp-client-2025-11-20` usando la [guida alla migrazione](https://platform.claude.com/docs/it/agents-and-tools/mcp-connector#migration-guide) precedente.
La versione precedente del connettore MCP includeva la configurazione degli strumenti direttamente nella definizione del server 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"]
}
}
]
}
```
### Descrizione dei campi deprecati
| Proprietà | Tipo | Descrizione |
| ---------------------------------- | ------- | ------------------------------------------------------------------- |
| `tool_configuration` | object | **Deprecato:** Usa invece MCPToolset nell'array `tools` |
| `tool_configuration.enabled` | boolean | **Deprecato:** Usa `default_config.enabled` in MCPToolset |
| `tool_configuration.allowed_tools` | array | **Deprecato:** Usa il pattern allowlist con `configs` in MCPToolset |