SpyBara
Go Premium

agent-sdk/mcp.md 2026-05-07 22:59 UTC to 2026-05-08 22:00 UTC

772 added, 0 removed.

2026
Sun 31 06:39 Sat 30 06:23 Fri 29 06:38 Thu 28 06:37 Wed 27 06:42 Tue 26 06:33 Sun 24 06:25 Sat 23 06:18 Fri 22 06:33 Thu 21 06:36 Wed 20 06:35 Tue 19 06:34 Mon 18 23:59 Sun 17 01:01 Fri 15 22:58 Thu 14 17:02 Wed 13 23:01 Tue 12 22:57 Mon 11 23:00 Sun 10 23:03 Sat 9 04:57 Fri 8 22:00 Thu 7 22:59 Tue 5 23:00 Mon 4 22:58 Sat 2 18:14 Fri 1 18:19

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.

Aggiungi un server MCP

Puoi configurare i server MCP nel codice quando chiami query(), oppure in un file .mcp.json caricato tramite settingSources.

Nel codice

Passa i server MCP direttamente nell'opzione mcpServers:

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

Crea un file .mcp.json nella radice del tuo progetto. Il file viene rilevato quando la fonte di impostazione project è abilitata, il che è il caso per le opzioni predefinite di query(). Se imposti settingSources esplicitamente, includi "project" affinché questo file venga caricato:

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

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.

Concedi accesso con allowedTools

Utilizza allowedTools per specificare quali strumenti MCP Claude può utilizzare:

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 (*) ti permettono di consentire tutti gli strumenti da un server senza elencare ciascuno individualmente.

Scopri gli strumenti disponibili

Per vedere quali strumenti fornisce un server MCP, controlla la documentazione del server o connettiti al server e ispeziona il messaggio di inizializzazione system:

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

Tipi di trasporto

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

  • Se la documentazione ti fornisce un comando da eseguire (come npx @modelcontextprotocol/server-github), utilizza stdio
  • Se la documentazione ti fornisce un URL, utilizza HTTP o SSE
  • Se stai costruendo i tuoi strumenti personalizzati nel codice, utilizza un server MCP SDK

Server stdio

Processi locali che comunicano tramite stdin/stdout. Utilizza questo per i server MCP che esegui sulla stessa macchina:

const _ = {
options: {
mcpServers: {
github: {
command: "npx",
args: ["-y", "@modelcontextprotocol/server-github"],
env: {
GITHUB_TOKEN: process.env.GITHUB_TOKEN
}
}
},
allowedTools: ["mcp__github__list_issues", "mcp__github__search_issues"]
}
};

Server HTTP/SSE

Utilizza HTTP o SSE per i server MCP ospitati nel cloud e le API remote:

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 HTTP (non-streaming), utilizza "type": "http" invece.

Server MCP SDK

Definisci strumenti personalizzati direttamente nel codice della tua applicazione invece di eseguire un processo server separato. Consulta la guida agli strumenti personalizzati per i dettagli di implementazione.

Ricerca di strumenti MCP

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

La ricerca di strumenti è abilitata per impostazione predefinita. Consulta Ricerca di strumenti per le opzioni di configurazione e i dettagli.

Per ulteriori dettagli, incluse le best practice e l'utilizzo della ricerca di strumenti con strumenti SDK personalizzati, consulta la guida alla ricerca di strumenti.

Autenticazione

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

Passa le credenziali tramite variabili di ambiente

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

const _ = {
options: {
mcpServers: {
github: {
command: "npx",
args: ["-y", "@modelcontextprotocol/server-github"],
env: {
GITHUB_TOKEN: process.env.GITHUB_TOKEN
}
}
},
allowedTools: ["mcp__github__list_issues"]
}
};

Consulta Elenca i problemi da un repository per un esempio completo e funzionante con registrazione di debug.

Intestazioni HTTP per server remoti

Per i server HTTP e SSE, passa 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__*"]
}
};

Autenticazione OAuth2

La specifica MCP supporta OAuth 2.1 per l'autorizzazione. L'SDK non gestisce i flussi OAuth automaticamente, ma puoi passare i token di accesso tramite intestazioni dopo aver completato il flusso OAuth nella tua applicazione:

// After completing OAuth flow in your app
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

Elenca i problemi da un repository

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

Prima di eseguire, crea un token di accesso personale GitHub con ambito repo e impostalo come variabile di ambiente:

export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx

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: {
command: "npx",
args: ["-y", "@modelcontextprotocol/server-github"],
env: {
GITHUB_TOKEN: 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);
}
}

Interroga un database

Questo esempio utilizza il server Postgres MCP per interrogare un database. La stringa di connessione viene passata come argomento al server. L'agente scopre automaticamente lo schema del database, scrive la query SQL e restituisce i risultati:

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

// Connection string from environment variable
const connectionString = process.env.DATABASE_URL;

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",
// Pass connection string as argument to the server
args: ["-y", "@modelcontextprotocol/server-postgres", connectionString]
}
},
// Allow only read queries, not writes
allowedTools: ["mcp__postgres__query"]
}
})) {
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 o un server remoto potrebbe essere irraggiungibile.

L'SDK emette un messaggio system con sottotipo init all'inizio di ogni query. Questo messaggio include lo stato della connessione per ogni server MCP. Controlla il campo status per rilevare gli errori di connessione prima che l'agente inizi a lavorare:

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

for await (const message of query({
prompt: "Process data",
options: {
mcpServers: {
"data-processor": dataServer
}
}
})) {
if (message.type === "system" && message.subtype === "init") {
const failedServers = message.mcp_servers.filter((s) => s.status !== "connected");

if (failedServers.length > 0) {
console.warn("Failed to connect:", failedServers);
}
}

if (message.type === "result" && message.subtype === "error_during_execution") {
console.error("Execution failed");
}
}

Troubleshooting

Il server mostra lo stato "failed"

Controlla 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`);
    }
  }
}

Cause comuni:

  • Variabili di ambiente mancanti: Assicurati che i token e le credenziali richiesti siano impostati. Per i server stdio, controlla che il campo env corrisponda a quello che il server si aspetta.
  • Server non installato: Per i comandi npx, verifica che il pacchetto esista e che Node.js sia nel tuo PATH.
  • Stringa di connessione non valida: Per i server di database, verifica il formato della stringa di connessione e che il database sia accessibile.
  • Problemi di rete: Per i server HTTP/SSE remoti, controlla che l'URL sia raggiungibile e che eventuali firewall consentano la connessione.

Gli strumenti non vengono chiamati

Se Claude vede gli strumenti ma non li utilizza, controlla di aver concesso l'autorizzazione con allowedTools:

const _ = {
  options: {
    mcpServers: {
      // your servers
    },
    allowedTools: ["mcp__servername__*"] // Required for Claude to use the tools
  }
};

Timeout della connessione

L'SDK MCP ha un timeout predefinito di 60 secondi per le connessioni del server. Se il tuo server impiega più tempo per avviarsi, la connessione avrà esito negativo. Per i server che hanno bisogno di più tempo di avvio, considera:

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

Risorse correlate