MCP e collegamento agli strumenti

Avanzato

Il Model Context Protocol (MCP) è lo standard aperto per collegare l'AI a strumenti e dati esterni. Sull'API non devi eseguire alcun client MCP: il connettore MCP ti permette di indicare un server remoto nella richiesta e Claude ne chiama gli strumenti dentro il normale loop dell'agent. Due campi della richiesta sostituiscono un intero livello di integrazione.

What you'll learn

Quando il connettore MCP batte la definizione a mano degli strumenti — e quando no
La forma esatta della richiesta: mcp_servers per la connessione, mcp_toolset per la policy
Allowlist, denylist e configurazione per singolo strumento — e come si fondono i tre livelli di config
I blocchi di risposta che devi gestire: mcp_tool_use e mcp_tool_result
I limiti veri: solo HTTPS, solo strumenti, buchi di piattaforma e nessuna copertura ZDR

MCP vs strumenti definiti a mano

	Uso degli strumenti (personalizzati)	Connettore MCP
Cosa definisci	Lo schema di ogni strumento, e lo esegui tu	Una connessione a un server che pubblica strumenti
Chi esegue lo strumento	Il tuo codice, nel tuo loop	È il lato Anthropic a chiamare il server remoto
Ideale per	Poche funzioni su misura nella tua app	Riutilizzare integrazioni esistenti (GitHub, database, browser, SaaS)
Auth	Il tuo codice	Un bearer token OAuth che fornisci tu per ciascun server

Coesistono. Definisci direttamente gli strumenti specifici della tua app e attingi a capacità già pronte tramite MCP.

La forma della richiesta

Due pezzi, tenuti separati di proposito: mcp_servers dice dov'è il server e come autenticarsi; la voce mcp_toolset nell'array tools dice quali dei suoi strumenti sei disposto a esporre e come.

Guided walkthrough1 of 4

anthropic-beta: mcp-client-2025-11-20 — senza di esso il campo mcp_servers non viene accettato. Negli SDK corrisponde alla lista betas in una chiamata beta.messages.create.

Chiamata minima al connettore MCP (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": "MODEL_ID",
  "max_tokens": 1000,
  "messages": [{"role": "user", "content": "What tools do you have available?"}],
  "mcp_servers": [
    {"type": "url", "url": "https://example.com/sse", "name": "example-mcp", "authorization_token": "YOUR_TOKEN"}
  ],
  "tools": [
    {"type": "mcp_toolset", "mcp_server_name": "example-mcp"}
  ]
}'

:::tip Non scrivere mai il modello in modo fisso MODEL_ID qui sopra è un segnaposto voluto. Leggi l'ID attuale da Modelli e prezzi attuali e tienilo in configurazione, così un aggiornamento del modello è una modifica di una riga. :::

L'API impone un abbinamento rigido: ogni server in mcp_servers deve essere referenziato da esattamente un toolset, e il mcp_server_name di ogni toolset deve corrispondere a un server dichiarato. Le discordanze sono errori di validazione, non silenziosi no-op.

Scegli cosa Claude può fare davvero

È la parte che la maggior parte delle integrazioni sbaglia. Un toolset accetta un default_config applicato a ogni strumento, più configs con override per singolo strumento. Precedenza, dalla più alta: configs per strumento → default_config a livello di set → valori predefiniti di sistema.

Denylist — abilita tutto, poi spegni i pericolosi. Ragionevole quando vuoi ampiezza ma nessuna scrittura distruttiva:

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

Allowlist — disabilita per impostazione predefinita, poi nomina i sopravvissuti. È la postura a privilegio minimo, quella da preferire per default:

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

:::warning Una denylist blocca solo ciò a cui hai pensato I server possono aggiungere strumenti. Una denylist concede silenziosamente ogni strumento pubblicato dopo che l'hai scritta; una allowlist li ignora silenziosamente. Per qualsiasi cosa tocchi dati dei clienti o denaro, usa una allowlist. Nota inoltre che nominare in configs uno strumento che non esiste sul server produce un warning nei log del backend ma non un errore — quindi un refuso in una allowlist disabilita in silenzio proprio lo strumento che volevi abilitare. Verifica sulla lista di strumenti live del server. :::

Tieni gli schemi fuori dal contesto

La descrizione di ogni strumento abilitato viene inviata con la richiesta, quindi un catalogo grasso tassa ogni turno. La risposta del connettore è defer_loading: true: la descrizione resta fuori dal contesto iniziale e Claude la richiama su richiesta tramite il Tool Search Tool.

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

Leggilo così: differisci tutto tranne l'unico strumento da cui questo task parte. Un toolset accetta anche cache_control, così un catalogo stabile può stare dietro un breakpoint di prompt caching invece di essere rifatturato a ogni turno. Per i numeri dietro tutto questo — e per capire perché differire gli strumenti ha aumentato l'accuratezza di selezione invece di ridurla — vedi La tassa sui token di MCP. Quando a inondare il contesto sono i risultati e non le definizioni, usa invece Programmatic Tool Calling.

Cosa torna indietro

Due tipi di blocco di contenuto che devi gestire:

{ "type": "mcp_tool_use", "id": "mcptoolu_...", "name": "echo",
  "server_name": "example-mcp", "input": { "param1": "value1" } }

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

Nota server_name sul blocco d'uso: con più server collegati, è così che attribuisci una chiamata — essenziale per i log e per capire quale integrazione si è comportata male. E is_error è un campo, non un'eccezione: uno strumento MCP che fallisce torna come risultato, quindi il tuo loop deve ispezionarlo invece di dare per scontato il successo.

I limiti che fanno male

Watch out

Solo strumenti. Della specifica MCP, il connettore supporta attualmente le chiamate agli strumenti — non prompt né risorse. Ti servono? Esegui un client tuo e usa gli helper MCP degli SDK.
Solo HTTPS remoto. Il server deve essere raggiungibile pubblicamente via HTTP (transport Streamable HTTP o SSE). Un server stdio locale non può essere collegato così — è ciò che fanno Claude Code e le app desktop.
Buchi di piattaforma. Disponibile su Claude API, Claude Platform su AWS e Microsoft Foundry (deployment Hosted-on-Anthropic). Attualmente non su Amazon Bedrock né Google Cloud.
Nessuna zero-data-retention. I dati scambiati con i server MCP — definizioni degli strumenti e risultati di esecuzione — rientrano nella retention standard, non nella ZDR.
OAuth è affar tuo. L'API accetta un authorization_token; ottenerlo e rinnovarlo prima della scadenza spetta a te.

Stesso standard, tre superfici

API (questa pagina) — server remoti per URL, tramite il connettore.
Claude Code — server locali e remoti nelle tue sessioni di sviluppo.
Le app — MCP alimenta i Connettori.

Impara il protocollo una volta; si trasferisce. Cambia solo il cablaggio.

Fiducia

:::warning Un server MCP è codice più accesso Collega solo server di cui ti fidi, limitali al privilegio minimo con una allowlist e ricorda che i contenuti restituiti da un server sono input non fidati che possono trasportare prompt injection. Esamina i server di terze parti prima di collegarli — Esaminare codice di terze parti e Mettere in sicurezza i server MCP. :::

Vocabolario del connettore MCP

Premi Invio o Spazio per girare la carta. Usa le frecce sinistra e destra per spostarti tra le carte.Termine mostrato.

1 / 6

Mettiti alla prova

0/4

Vuoi che Claude usi solo search_events e create_event di un server calendario. Qual è la forma corretta del toolset?
Una chiamata a uno strumento MCP fallisce. Dove appare?
Ti serve che Claude legga risorse MCP da un server stdio locale. Il connettore può farlo?
Il tuo catalogo di strumenti si estende su quattro server e domina la finestra di contesto a ogni turno. Prima mossa più economica?

Key takeaways

Il connettore sostituisce un client MCP con due campi della richiesta — ma solo per server HTTPS remoti e solo per chiamate a strumenti.
mcp_servers è la connessione; il mcp_toolset in tools è la policy. Ogni server deve abbinarsi a esattamente un toolset.
La allowlist (default_config.enabled false, più configs esplicite) batte la denylist: gli strumenti aggiunti al server in seguito vengono ignorati, non concessi.
defer_loading e cache_control sono le tue leve quando gli schemi degli strumenti iniziano a mangiare la finestra di contesto.
Gestisci i blocchi mcp_tool_use e mcp_tool_result — incluso is_error, che è un campo, non un'eccezione.
Controlla l'header beta prima di andare in produzione: mcp-client-2025-11-20 è quello attuale, mcp-client-2025-04-04 è deprecato.

Fonti e approfondimenti

Connettore MCP — documentazione Anthropic — il riferimento autorevole sui campi e la guida alla migrazione.
Specifica del Model Context Protocol — lo standard aperto stesso, autorizzazione inclusa.

MCP vs strumenti definiti a mano​

La forma della richiesta​

Chiamata minima al connettore MCP (cURL)

Scegli cosa Claude può fare davvero​

Tieni gli schemi fuori dal contesto​

Cosa torna indietro​

I limiti che fanno male​

Stesso standard, tre superfici​

Fiducia​