Connettiti a strumenti esterni con MCP

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 eseguirsi 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 sui hook e restituisce i risultati.

Aggiungi un server MCP

Puoi configurare i server MCP nel codice quando chiami query(), o in un file .mcp.json che l'SDK carica automaticamente.

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. L'SDK lo carica automaticamente:

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

Consenti strumenti MCP

Gli strumenti MCP richiedono un permesso esplicito prima che Claude possa usarli. Senza permesso, 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:

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.

Alternativa: Cambia la modalità di permesso

Invece di elencare gli strumenti consentiti, puoi cambiare la modalità di permesso per concedere un accesso più ampio:

• permissionMode: "acceptEdits": Approva automaticamente l'utilizzo dello strumento (richiede comunque conferma per operazioni distruttive)
• permissionMode: "bypassPermissions": Salta tutti i prompt di sicurezza, inclusi quelli per operazioni distruttive come l'eliminazione di file o l'esecuzione di comandi shell. Usa con cautela, specialmente in produzione. Questa modalità si propaga ai subagenti generati dallo strumento Task.

options: {
  mcpServers: { /* your servers */ },
  permissionMode: "acceptEdits"  // No need for allowedTools
}

Vedi Permissions per ulteriori dettagli sulle modalità di permesso.

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), usa stdio
• Se la documentazione ti fornisce un URL, usa HTTP o SSE
• Se stai costruendo i tuoi strumenti nel codice, usa un server MCP SDK

Server stdio

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

Server HTTP/SSE

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

Per HTTP (non-streaming), usa "type": "http" invece.

Server MCP SDK

Definisci strumenti personalizzati direttamente nel codice della tua applicazione invece di eseguire un processo server separato. Vedi 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 MCP risolve questo problema caricando dinamicamente gli strumenti su richiesta invece di precaricarli tutti.

Come funziona

La ricerca di strumenti viene eseguita in modalità automatica per impostazione predefinita. Si attiva quando le descrizioni dei tuoi strumenti MCP consumerebbero più del 10% della finestra di contesto. Quando attivata:

1. Gli strumenti MCP sono contrassegnati con defer_loading: true piuttosto che caricati nel contesto in anticipo
2. Claude utilizza uno strumento di ricerca per scoprire gli strumenti MCP rilevanti quando necessario
3. Solo gli strumenti che Claude effettivamente ha bisogno vengono caricati nel contesto

La ricerca di strumenti richiede modelli che supportano i blocchi tool_reference: Sonnet 4 e versioni successive, oppure Opus 4 e versioni successive. I modelli Haiku non supportano la ricerca di strumenti.

Configura la ricerca di strumenti

Controlla il comportamento della ricerca di strumenti con la variabile di ambiente ENABLE_TOOL_SEARCH:

Imposta il valore nell'opzione env:

const options = {
  mcpServers: { /* your MCP servers */ },
  env: {
    ENABLE_TOOL_SEARCH: "auto:5"  // Enable at 5% threshold
  }
};

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:

Vedi Elenca i problemi da un repository per un esempio completo e funzionante con debug logging.

Intestazioni HTTP per server remoti

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

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 debug logging 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.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 i guasti 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");
  }
}

Risoluzione dei problemi

Il server mostra lo stato "failed"

Controlla il messaggio init per vedere quali server non si sono connessi:

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 il permesso con allowedTools o cambiando la modalità di permesso:

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

• Guida agli strumenti personalizzati: Costruisci il tuo server MCP che viene eseguito in-process con la tua applicazione SDK
• Permissions: Controlla quali strumenti MCP il tuo agente può utilizzare con allowedTools e disallowedTools
• Riferimento SDK TypeScript: Riferimento API completo incluse le opzioni di configurazione MCP
• Riferimento SDK Python: Riferimento API completo incluse le opzioni di configurazione MCP
• Directory dei server MCP: Sfoglia i server MCP disponibili per database, API e altro