SpyBara
Go Premium

agent-sdk/mcp.md 2026-09-11 23:01 UTC to 2026-09-12 03:02 UTC

This page contains 3 additions and 1 deletion.

2026
Wed 9 22:58 Sat 12 03:02 Mon 14 22:58 Fri 18 23:58

Connettiti a strumenti esterni con MCP

Configura i server MCP per estendere il tuo agente con strumenti esterni. Copre i tipi di trasporto, la ricerca di strumenti per set di strumenti di grandi dimensioni, l'autenticazione e la gestione degli errori.

Il Model Context Protocol (MCP) è uno standard aperto per connettere agenti AI a strumenti e fonti di dati esterni. Con MCP, il tuo agente può interrogare database, integrarsi con API come Slack e GitHub e connettersi ad altri servizi senza scrivere implementazioni di strumenti personalizzate.

I server MCP possono essere eseguiti come processi locali, connettersi tramite HTTP o essere eseguiti direttamente all'interno della tua applicazione SDK.

Quickstart

Questo esempio si connette al server MCP della documentazione di Claude Code utilizzando il trasporto HTTP e utilizza allowedTools con un carattere jolly per consentire tutti gli strumenti dal server.

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
prompt: "Use the docs MCP server to explain what hooks are in Claude Code",
options: {
mcpServers: {
"claude-code-docs": {
type: "http",
url: "https://code.claude.com/docs/mcp"
}
},
allowedTools: ["mcp__claude-code-docs__*"]
}
})) {
if (message.type === "result" && message.subtype === "success") {
console.log(message.result);
}
}

L'agente si connette al server di documentazione, cerca informazioni su hooks e restituisce i risultati.

Aggiungere un server MCP

È possibile configurare i server MCP nel codice quando si chiama query(), oppure in un file .mcp.json caricato tramite settingSources.

Nel codice

Passare i server MCP direttamente nell'opzione mcpServers. Questo esempio avvia un server MCP del filesystem locale per /Users/me/projects. Sostituire quel percorso con una directory sulla propria macchina:

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
prompt: "List files in my project",
options: {
mcpServers: {
filesystem: {
command: "npx",
args: ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/projects"]
}
},
allowedTools: ["mcp__filesystem__*"]
}
})) {
if (message.type === "result" && message.subtype === "success") {
console.log(message.result);
}
}

Da un file di configurazione

Creare un file .mcp.json nella radice del progetto. Il file viene rilevato quando la sorgente di impostazione project è abilitata, il che avviene per le opzioni predefinite di query(). Se si imposta settingSources esplicitamente, includere "project" affinché questo file venga caricato. Sostituire /Users/me/projects con una directory sulla propria macchina:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/projects"]
    }
  }
}

Tempistica della connessione

Claude Code registra i server che passate in options.mcpServers all'avvio e invia il messaggio init una volta che l'attesa del primo turno, se presente, si risolve. Senza options.mcpServers, Claude Code attende 2 secondi per i server in sospeso prima del primo turno, quindi i server caricati da file di configurazione come .mcp.json comunemente mostrano pending all'init. Quando ogni server options.mcpServers si connette, e se ritarda il primo turno, dipende dal suo tipo:

Tipo di server Ritarda il primo turno? Timeout di attesa del primo turno
server stdio, o server HTTP/SSE senza un elenco di strumenti memorizzato nella cache Sì, fino a quando non si connette MCP_TIMEOUT, 30 secondi per impostazione predefinita; la connessione non riesce a quella scadenza
Server remoto con un elenco di strumenti memorizzato nella cache, salvato da Claude Code da una connessione precedente No; gli strumenti memorizzati nella cache sono disponibili dal primo turno Nessuno; si connette alla sua prima chiamata di strumento, e quella connessione differita ha il suo proprio timeout
Server SDK in-process No; non ritarda mai il primo turno Nessuno

Per bloccare l'avvio stesso in una fase separata e precedente rispetto all'attesa del primo turno, prima che il messaggio init sia inviato:

  • Impostare MCP_CONNECTION_NONBLOCKING a 0 per bloccare l'intero batch di connessione. Claude Code limita tale attesa a 5 secondi per impostazione predefinita. Regolare il limite con la variabile di ambiente MCP_CONNECT_TIMEOUT_MS, in millisecondi. I server ancora in sospeso a quella scadenza continuano a connettersi in background.
  • Impostare alwaysLoad: true sulla configurazione di un server per rendere i suoi strumenti disponibili ai loro schemi completi al primo turno, esenti dal differimento della ricerca degli strumenti. Claude Code attende all'avvio gli strumenti di quel server, limitati alla stessa scadenza, mentre gli altri server continuano a connettersi in background; un server remoto con un elenco di strumenti memorizzato nella cache li fornisce senza connettersi, secondo la tabella sopra.

Il messaggio system con sottotipo init segnala lo stato di ogni server nel momento in cui viene emesso; vedere Gestione degli errori per leggere questi stati.

Consenti strumenti MCP

Gli strumenti MCP richiedono un'autorizzazione esplicita prima che Claude possa utilizzarli. Senza autorizzazione, Claude vedrà che gli strumenti sono disponibili ma non sarà in grado di chiamarli.

Convenzione di denominazione degli strumenti

Gli strumenti MCP seguono il modello di denominazione mcp__<server-name>__<tool-name>. Ad esempio, un server GitHub denominato "github" con uno strumento list_issues diventa mcp__github__list_issues.

Auto-approvazione con allowedTools

Utilizzare allowedTools per approvare automaticamente strumenti MCP specifici in modo che Claude possa utilizzarli senza un prompt di autorizzazione:

const _ = {
options: {
mcpServers: {
// your servers
},
allowedTools: [
"mcp__github__*", // All tools from the github server
"mcp__db__query", // Only the query tool from db server
"mcp__slack__send_message" // Only send_message from slack server
]
}
};

I caratteri jolly (*) consentono di approvare tutti gli strumenti da un server senza elencare singolarmente ciascuno.

Scopri gli strumenti disponibili

Per vedere quali strumenti fornisce un server MCP, controllare la documentazione del server o ispezionare l'array tools nel messaggio di inizializzazione system. I nomi degli strumenti MCP iniziano con mcp__.

Claude Code emette il messaggio di inizializzazione dopo l'attesa di connessione al primo turno per i server passati in options.mcpServers, quindi l'array tools elenca gli strumenti mcp__ di ciascun server che si è connesso entro quel momento, più quelli dei server con un elenco di strumenti memorizzato nella cache, che si connettono al primo utilizzo. Gli strumenti di qualsiasi altro server che non si è ancora connesso sono assenti; vedere Gestione degli errori per leggere lo stato di ciascun server.

Questo filtro stampa i nomi degli strumenti MCP:

import { query } from "@anthropic-ai/claude-agent-sdk";

const options = {
mcpServers: {
// your servers
},
};

for await (const message of query({ prompt: "...", options })) {
if (message.type === "system" && message.subtype === "init") {
const mcpTools = message.tools.filter((name) => name.startsWith("mcp__"));
console.log("Available MCP tools:", mcpTools);
}
}

Potete anche chiedere a Claude di elencare gli strumenti disponibili da un server.

Tipi di trasporto

I server MCP comunicano con il vostro agente utilizzando diversi protocolli di trasporto. Controllate la documentazione del server per vedere quale trasporto supporta:

  • Se la documentazione vi fornisce un comando da eseguire (come npx @modelcontextprotocol/server-filesystem), utilizzate stdio
  • Se la documentazione vi fornisce un URL, utilizzate HTTP o SSE
  • Se state costruendo i vostri strumenti personalizzati nel codice, utilizzate un server MCP SDK

Server stdio

Processi locali che comunicano tramite stdin/stdout. Utilizzate questo per i server MCP che eseguite sulla stessa macchina. Per il modulo .mcp.json, utilizzate gli stessi campi mostrati in Da un file di configurazione. Nel codice, passate il comando e i suoi argomenti. Sostituite /Users/me/projects con una directory sulla vostra macchina:

const _ = {
options: {
mcpServers: {
filesystem: {
command: "npx",
args: ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/projects"]
}
},
allowedTools: ["mcp__filesystem__read_file", "mcp__filesystem__list_directory"]
}
};

Server HTTP/SSE

Utilizzate HTTP o SSE per i server MCP ospitati nel cloud e le API remote. Per il modulo .mcp.json, utilizzate gli stessi campi dell'esempio in Intestazioni HTTP per server remoti, con "type": "sse" per un server SSE. Nel codice, passate l'URL del server:

const _ = {
options: {
mcpServers: {
"remote-api": {
type: "sse",
url: "https://api.example.com/mcp/sse",
headers: {
Authorization: `Bearer ${process.env.API_TOKEN}`
}
}
},
allowedTools: ["mcp__remote-api__*"]
}
};

Per il trasporto HTTP trasmissibile, utilizzate "type": "http" invece. Nei file di configurazione .mcp.json e altri file JSON, "streamable-http" è accettato come alias per "http". Il tipo McpHttpServerConfig degli SDK dichiara solo "http", quindi utilizzate "http" per i server che passate nel codice.

Server MCP SDK

Definite strumenti personalizzati direttamente nel codice della vostra applicazione invece di eseguire un processo server separato. Consultate la guida agli strumenti personalizzati per i dettagli di implementazione.

Un server MCP SDK registrato da una richiesta di controllo initialize inizia a connettersi non appena Claude Code elabora la richiesta.

Quando hai molti MCP tool configurati, le definizioni dei tool possono consumare una parte significativa della tua finestra di contesto. La ricerca dei tool risolve questo problema trattenendo le definizioni dei tool dal contesto e caricando solo quelli di cui Claude ha bisogno per ogni turno.

La ricerca dei tool è abilitata per impostazione predefinita. Vedi Tool search per le opzioni di configurazione, le best practice e l'utilizzo della ricerca dei tool con i tool SDK personalizzati.

Autenticazione

La maggior parte dei server MCP richiede l'autenticazione per accedere ai servizi esterni. Passare le credenziali tramite variabili di ambiente nella configurazione del server.

Passare le credenziali tramite variabili di ambiente

Utilizzare il campo env per passare chiavi API, token e altre credenziali al server MCP:

const _ = {
options: {
mcpServers: {
"api-server": {
command: "npx",
args: ["-y", "@your-org/api-mcp-server"],
env: {
API_KEY: process.env.API_KEY
}
}
},
allowedTools: ["mcp__api-server__*"]
}
};

Intestazioni HTTP per server remoti

Per i server HTTP e SSE, passare le intestazioni di autenticazione direttamente nella configurazione del server:

const _ = {
options: {
mcpServers: {
"secure-api": {
type: "http",
url: "https://api.example.com/mcp",
headers: {
Authorization: `Bearer ${process.env.API_TOKEN}`
}
}
},
allowedTools: ["mcp__secure-api__*"]
}
};

Per un esempio completo e funzionante di un server remoto autenticato con intestazioni, vedere Elencare i problemi da un repository.

Autenticazione OAuth2

La specifica MCP supporta OAuth 2.1 per l'autorizzazione. L'SDK non apre un browser né esegue un flusso OAuth interattivo. Quando un server configurato restituisce una sfida di autorizzazione e nessun token memorizzato è disponibile, l'esecuzione dell'agente continua senza gli strumenti di quel server, e il server segnala lo stato needs-auth. L'array mcp_servers del messaggio di inizializzazione del sistema potrebbe comunque mostrare pending per quel server quando viene emesso. Per confermare se un server necessita di credenziali, eseguire il polling di mcpServerStatus() nell'SDK TypeScript o get_mcp_status() in Python.

Per fornire le credenziali, completare il flusso OAuth nella propria applicazione e passare il token di accesso risultante nelle headers del server:

// After completing OAuth flow in your app.
// Implement getAccessTokenFromOAuthFlow for your OAuth provider.
const accessToken = await getAccessTokenFromOAuthFlow();

const options = {
mcpServers: {
"oauth-api": {
type: "http",
url: "https://api.example.com/mcp",
headers: {
Authorization: `Bearer ${accessToken}`
}
}
},
allowedTools: ["mcp__oauth-api__*"]
};

Esempi

Elencare i problemi da un repository

Questo esempio si connette al server MCP GitHub remoto per elencare i problemi recenti. L'esempio include la registrazione del debug per verificare la connessione MCP e le chiamate agli strumenti.

Prima di eseguire, crea un token di accesso personale GitHub con accesso in lettura ai repository che desideri interrogare e impostalo come variabile di ambiente:

export GITHUB_TOKEN=YOUR_GITHUB_PAT

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
prompt: "List the 3 most recent issues in anthropics/claude-code",
options: {
mcpServers: {
github: {
type: "http",
url: "https://api.githubcopilot.com/mcp/",
headers: {
Authorization: `Bearer ${process.env.GITHUB_TOKEN}`
}
}
},
allowedTools: ["mcp__github__list_issues"]
}
})) {
// Verify MCP server connected successfully
if (message.type === "system" && message.subtype === "init") {
console.log("MCP servers:", message.mcp_servers);
}

// Log when Claude calls an MCP tool
if (message.type === "assistant") {
for (const block of message.message.content) {
if (block.type === "tool_use" && block.name.startsWith("mcp__")) {
console.log("MCP tool called:", block.name);
}
}
}

// Print the final result
if (message.type === "result" && message.subtype === "success") {
console.log(message.result);
}
}

Nella riga MCP servers:, uno status di connected per github conferma che il token funziona. Se Claude Code ha un elenco di strumenti memorizzato nella cache per il server, lo stato può leggere pending invece e il server si connette alla sua prima chiamata di strumento. Se lo stato è failed o needs-auth, vedi Gestione degli errori prima di fidarti del risultato, poiché Claude può ricorrere agli strumenti integrati quando il server non è disponibile.

Interrogare un database

Questo esempio utilizza DBHub per interrogare un database Postgres. L'agente scopre automaticamente lo schema del database, scrive la query SQL e restituisce i risultati.

Lo strumento execute_sql di DBHub esegue qualsiasi SQL che l'agente emette, incluse le scritture, a meno che non lo limiti. Impostando readonly = true nel file di configurazione di DBHub, DBHub rifiuta le istruzioni INSERT, UPDATE, DELETE e DDL, quindi l'esempio non può modificare i tuoi dati anche se l'agente emette una scrittura. DBHub risolve ${DATABASE_URL} dall'ambiente del processo quando carica la configurazione, quindi la stringa di connessione rimane fuori dal file. Crea questo dbhub.toml accanto al tuo script:

[[sources]]
id = "production"
dsn = "${DATABASE_URL}"

[[tools]]
name = "execute_sql"
source = "production"
readonly = true

Lo script quindi punta DBHub al file di configurazione invece di passare una stringa di connessione direttamente. Prima di eseguire, imposta la variabile di ambiente DATABASE_URL sulla tua stringa di connessione. Sostituisci i valori segnaposto con i dettagli del tuo database:

export DATABASE_URL=postgresql://user:password@localhost:5432/mydb

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
// Natural language query - Claude writes the SQL
prompt: "How many users signed up last week? Break it down by day.",
options: {
mcpServers: {
postgres: {
command: "npx",
// dbhub.toml sets readonly = true, so execute_sql rejects writes
args: ["-y", "@bytebase/dbhub", "--config", "dbhub.toml"]
}
},
allowedTools: ["mcp__postgres__execute_sql"]
}
})) {
if (message.type === "result" && message.subtype === "success") {
console.log(message.result);
}
}

Gestione degli errori

I server MCP possono non riuscire a connettersi per vari motivi: il processo del server potrebbe non essere installato, le credenziali potrebbero non essere valide, oppure un server remoto potrebbe essere irraggiungibile.

Claude Code emette un messaggio system con sottotipo init all'inizio di ogni query. Questo messaggio include lo stato della connessione per ogni server MCP. Il campo status può essere "pending", "connected", "failed", "needs-auth" o "disabled". Claude Code emette il messaggio init dopo l'attesa di connessione al primo turno per i server passati in options.mcpServers, quindi un server di questo tipo che si è connesso entro l'attesa mostra "connected".

Nel messaggio init, non trattare "pending" come un errore di per sé. Può significare uno di questi:

Verificare la presenza di "failed" o "needs-auth" per rilevare i server che non saranno utilizzabili:

import { query } from "@anthropic-ai/claude-agent-sdk";

try {
for await (const message of query({
prompt: "Process data",
options: {
mcpServers: {
// Replace dataServer with your server configuration
"data-processor": dataServer
}
}
})) {
if (message.type === "system" && message.subtype === "init") {
const unavailableServers = message.mcp_servers.filter(
(s) => s.status === "failed" || s.status === "needs-auth"
);

if (unavailableServers.length > 0) {
console.warn("Unavailable MCP servers:", unavailableServers);
}
}

if (message.type === "result" && message.subtype === "error_during_execution") {
console.error("Execution failed");
}
}
} catch (error) {
// A single-shot query() throws after yielding an error result. If the
// failure was an error result, the error subtype branch above has
// already run; a failure to start or reach the Claude Code process
// yields no result message. MCP servers that fail to connect don't
// throw: use the status check above, and note that servers still
// "pending" at init need a later status check.
console.log(`Session ended with an error: ${error}`);
}

Lo stato di un server remoto può anche cambiare dopo che segnala "connected". Quando la connessione ad esso si interrompe durante la sessione, Claude Code sposta il server di nuovo a "pending" mentre si riconnette. Una successiva chiamata a mcpServerStatus() in TypeScript, o ClaudeSDKClient.get_mcp_status() in Python, può quindi segnalare "pending" per un server che hai visto connesso in precedenza, senza alcun cambiamento di configurazione da parte tua.

Dopo che cinque tentativi di riconnessione falliscono, il server segnala "failed", o "needs-auth" quando ha bisogno di essere autorizzato di nuovo. Per riprovare manualmente, chiama reconnectMcpServer() in TypeScript o ClaudeSDKClient.reconnect_mcp_server() in Python.

Troubleshooting

Server shows "failed" status

Controllare il messaggio init per vedere quali server non hanno potuto connettersi:

if (message.type === "system" && message.subtype === "init") {
for (const server of message.mcp_servers) {
if (server.status === "failed") {
console.error(`Server ${server.name} failed to connect`);
}
}
}

Uno stato "pending" non significa che il server non abbia potuto connettersi. Vedere Error handling per i casi che copre all'init. Per ottenere stati aggiornati più avanti nella sessione, chiamare il metodo mcpServerStatus() della query in TypeScript SDK, oppure ClaudeSDKClient.get_mcp_status() in Python.

Cause comuni:

  • Missing environment variables: Assicurarsi che i token e le credenziali richiesti siano impostati. Per i server stdio, verificare che il campo env corrisponda a quello che il server si aspetta.
  • Server not installed: Per i comandi npx, verificare che il pacchetto esista e che Node.js sia nel vostro PATH.
  • Invalid connection string: Per i server di database, verificare il formato della stringa di connessione e che il database sia accessibile.
  • Network issues: Per i server HTTP/SSE remoti, controllare che l'URL sia raggiungibile e che eventuali firewall consentano la connessione.

Tools not being called

Se Claude vede gli strumenti ma non li utilizza, verificare di aver concesso il permesso con allowedTools:

const _ = {
options: {
mcpServers: {
// your servers
},
allowedTools: ["mcp__servername__*"] // Auto-approve calls from this server
}
};

Connection timeouts

Le connessioni del server MCP scadono dopo 30 secondi per impostazione predefinita. Per modificare il tempo massimo che una chiamata di strumento in esecuzione può richiedere, impostare MCP_TOOL_TIMEOUT. Se il vostro server impiega più tempo per avviarsi, la connessione non riesce. Aumentare il limite di connessione con la variabile di ambiente MCP_TIMEOUT, in millisecondi. Per i server che necessitano di più tempo di avvio, considerare anche:

  • Utilizzare un server più leggero se disponibile
  • Pre-riscaldare il server prima di avviare l'agente
  • Controllare i log del server per le cause di inizializzazione lenta

In TypeScript, è possibile impostare il limite di chiamata dello strumento per un singolo SDK MCP server passando timeout a createSdkMcpServer().

Tool output exceeds maximum allowed tokens

L'SDK applica lo stesso limite di output MCP di Claude Code. Quando il risultato di uno strumento senza contenuto di immagine è più grande di 25.000 token, Claude Code salva l'output in un file e sostituisce il risultato dello strumento con un messaggio di errore che nomina il percorso del file, in modo che l'agente possa leggere l'output in porzioni.

Aumentare il limite con la variabile di ambiente MAX_MCP_OUTPUT_TOKENS. Vedere MCP output limits and warnings per il comportamento completo, incluso il modo in cui un server può dichiarare un limite per strumento più elevato con l'annotazione anthropic/maxResultSizeChars.