Vai al contenuto principale
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.
Questa pagina copre la configurazione di MCP per l’Agent SDK. Per aggiungere server MCP al Claude Code CLI in modo che si carichino in ogni progetto, consulta Ambiti di installazione di MCP.

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.

Approvazione automatica con allowedTools

Utilizza 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 (*) ti permettono di consentire tutti gli strumenti da un server senza elencare ciascuno individualmente.
Preferisci allowedTools rispetto alle modalità di autorizzazione per l’accesso a MCP. permissionMode: "acceptEdits" non approva automaticamente gli strumenti MCP (solo le modifiche ai file e i comandi Bash del filesystem). permissionMode: "bypassPermissions" approva automaticamente gli strumenti MCP ma disabilita anche tutti gli altri prompt di sicurezza, il che è più ampio del necessario. Un carattere jolly in allowedTools concede esattamente il server MCP che desideri e niente di più. Consulta Modalità di autorizzazione per un confronto completo.

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 il trasporto HTTP in streaming, utilizza "type": "http" invece. Nei file di configurazione .mcp.json e altri file JSON, "streamable-http" è accettato come alias per "http". L’opzione programmatica mcpServers accetta solo "http".

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__*"] // Auto-approve calls from this server
  }
};

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