Connettore MCP

La funzionalità del connettore "Model Context Protocol", o MCP, di Claude ti consente di connetterti a server MCP remoti direttamente dalla Messages API senza un client MCP separato.

Funzionalità principali

• Integrazione API diretta: Connettiti ai server MCP senza implementare un client MCP
• Supporto per le chiamate agli strumenti: Accedi agli strumenti MCP tramite la Messages API
• Configurazione flessibile degli strumenti: Abilita tutti gli strumenti, consenti solo strumenti specifici tramite allowlist o escludi strumenti indesiderati tramite denylist
• Configurazione per singolo strumento: Configura singoli strumenti con impostazioni personalizzate
• Autenticazione OAuth: Supporto per token OAuth Bearer per server autenticati
• Server multipli: Connettiti a più server MCP in una singola richiesta

Quando Claude utilizza gli strumenti MCP

Una volta connesso un server MCP, Claude chiama i suoi strumenti quando la richiesta dell'utente corrisponde a una capacità descritta di uno strumento, sia esplicitamente ("cerca su Jira i bug aperti") sia implicitamente ("cosa sta bloccando il rilascio?" con un server Jira collegato).

Claude non chiama uno strumento MCP per domande di conoscenza generale su un servizio connesso. Chiedere "come funzionano i database di Notion?" con un server Notion collegato riceve una risposta diretta; chiedere "cosa c'è nel mio database Projects?" attiva lo strumento.

Puoi orientare la propensione di Claude a chiamare gli strumenti MCP tramite il tuo prompt di sistema. Consulta Quando Claude utilizza gli strumenti per indicazioni generali ed esempi di formulazione.

Limitazioni

• Dell'insieme di funzionalità della specifica MCP, attualmente sono supportate solo le chiamate agli strumenti.
• Il server deve essere esposto pubblicamente tramite HTTP (supporta sia il trasporto Streamable HTTP che SSE). I server STDIO locali non possono essere connessi direttamente.
• Il connettore MCP è disponibile sulla Claude API, su Claude Platform on AWS e su Microsoft Foundry. Attualmente non è disponibile su Amazon Bedrock o Vertex AI.

Utilizzo del connettore MCP nella Messages API

Il connettore MCP utilizza due componenti:

1. Definizione del server MCP (array mcp_servers): Definisce i dettagli di connessione al server (URL, autenticazione)
2. MCP Toolset (array tools): Configura quali strumenti abilitare e come configurarli

Esempio di base

Questo esempio abilita tutti gli strumenti di un server MCP con la configurazione predefinita:

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-4-8",
    max_tokens=1000,
    messages=[{"role": "user", "content": "What tools do you have available?"}],
    mcp_servers=[
        {
            "type": "url",
            "url": "https://example-server.modelcontextprotocol.io/sse",
            "name": "example-mcp",
            "authorization_token": "YOUR_TOKEN",
        }
    ],
    tools=[{"type": "mcp_toolset", "mcp_server_name": "example-mcp"}],
    betas=["mcp-client-2025-11-20"],
)

print(response)

Configurazione del server MCP

Ogni server MCP nell'array mcp_servers definisce i dettagli di connessione:

{
  "type": "url",
  "url": "https://example-server.modelcontextprotocol.io/sse",
  "name": "example-mcp",
  "authorization_token": "YOUR_TOKEN"
}

Descrizione dei campi

Configurazione dell'MCP toolset

L'MCPToolset risiede nell'array tools e configura quali strumenti del server MCP sono abilitati e come devono essere configurati.

Struttura di base

{
  "type": "mcp_toolset",
  "mcp_server_name": "example-mcp",
  "default_config": {
    "enabled": true,
    "defer_loading": false
  },
  "configs": {
    "specific_tool_name": {
      "enabled": true,
      "defer_loading": true
    }
  }
}

Descrizione dei campi

Opzioni di configurazione degli strumenti

Ogni strumento (sia configurato in default_config che in configs) supporta i seguenti campi:

Per la directory completa degli strumenti forniti da Anthropic e le proprietà opzionali come defer_loading, consulta il Riferimento degli strumenti. Per la ricerca su grandi set di strumenti, consulta lo strumento Tool search.

Unione delle configurazioni

I valori di configurazione vengono uniti con questa precedenza (dalla più alta alla più bassa):

1. Impostazioni specifiche dello strumento in configs
2. default_config a livello di set
3. Valori predefiniti di sistema

Esempio:

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

Risultato:

• search_events: enabled: false (da configs), defer_loading: true (da default_config)
• Tutti gli altri strumenti: enabled: true (predefinito di sistema), defer_loading: true (da default_config)

Pattern di configurazione comuni

Abilita tutti gli strumenti con la configurazione predefinita

Il pattern più semplice: abilita tutti gli strumenti di un server:

{
  "type": "mcp_toolset",
  "mcp_server_name": "google-calendar-mcp"
}

Allowlist: abilita solo strumenti specifici

Imposta enabled: false come predefinito, quindi abilita esplicitamente strumenti specifici:

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

Denylist: disabilita strumenti specifici

Abilita tutti gli strumenti per impostazione predefinita, quindi disabilita esplicitamente gli strumenti indesiderati. Escludere tramite denylist gli strumenti di scrittura o distruttivi è consigliato quando si creano assistenti di sola lettura, o quando si desidera un passaggio di conferma umana prima delle modifiche di stato:

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

Misto: allowlist con configurazione per singolo strumento

Combina l'allowlist con una configurazione personalizzata per ogni strumento:

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

In questo esempio:

• search_events è abilitato con defer_loading: false
• list_events è abilitato con defer_loading: true (ereditato da default_config)
• Tutti gli altri strumenti sono disabilitati

Regole di validazione

L'API applica queste regole di validazione:

• Il server deve esistere: Il mcp_server_name in un MCPToolset deve corrispondere a un server definito nell'array mcp_servers
• Il server deve essere utilizzato: Ogni server MCP definito in mcp_servers deve essere referenziato da esattamente un MCPToolset
• Toolset univoco per server: Ogni server MCP può essere referenziato da un solo MCPToolset
• Nomi di strumenti sconosciuti: Se un nome di strumento in configs non esiste sul server MCP, viene registrato un avviso nel backend ma non viene restituito alcun errore (i server MCP possono avere disponibilità dinamica degli strumenti)

Tipi di contenuto della risposta

Quando Claude utilizza gli strumenti MCP, la risposta include due nuovi tipi di blocchi di contenuto:

Blocco MCP tool use

{
  "type": "mcp_tool_use",
  "id": "mcptoolu_014Q35RayjACSWkSj4X2yov1",
  "name": "echo",
  "server_name": "example-mcp",
  "input": { "param1": "value1", "param2": "value2" }
}

Blocco MCP tool result

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

Server MCP multipli

Puoi connetterti a più server MCP includendo più definizioni di server in mcp_servers e un MCPToolset corrispondente per ciascuno nell'array tools:

{
  "model": "claude-opus-4-8",
  "max_tokens": 1000,
  "messages": [
    {
      "role": "user",
      "content": "Use tools from both mcp-server-1 and mcp-server-2 to complete this task"
    }
  ],
  "mcp_servers": [
    {
      "type": "url",
      "url": "https://mcp.example1.com/sse",
      "name": "mcp-server-1",
      "authorization_token": "TOKEN1"
    },
    {
      "type": "url",
      "url": "https://mcp.example2.com/sse",
      "name": "mcp-server-2",
      "authorization_token": "TOKEN2"
    }
  ],
  "tools": [
    {
      "type": "mcp_toolset",
      "mcp_server_name": "mcp-server-1"
    },
    {
      "type": "mcp_toolset",
      "mcp_server_name": "mcp-server-2",
      "default_config": {
        "defer_loading": true
      }
    }
  ]
}

Con molti strumenti disponibili, Claude seleziona in base ai nomi e alle descrizioni degli strumenti. Descrizioni chiare e specifiche degli strumenti migliorano l'accuratezza della selezione. Per grandi set di strumenti (decine di strumenti su più server), considera di abilitare defer_loading con lo strumento Tool search in modo che vengano mostrati solo gli strumenti rilevanti per ogni query.

Autenticazione

Per i server MCP che richiedono l'autenticazione OAuth, dovrai ottenere un token di accesso. La beta del connettore MCP supporta il passaggio di un parametro authorization_token nella definizione del server MCP. I consumatori dell'API devono gestire il flusso OAuth e ottenere il token di accesso prima di effettuare la chiamata API, e aggiornare il token secondo necessità.

Ottenere un token di accesso per i test

L'MCP inspector può guidarti attraverso il processo di ottenimento di un token di accesso a scopo di test.

1. Esegui l'inspector con il seguente comando. Devi avere Node.js installato sulla tua macchina.

   npx @modelcontextprotocol/inspector

   

2. Nella barra laterale a sinistra, per "Transport type", seleziona "SSE" o "Streamable HTTP".

3. Inserisci l'URL del server MCP.

4. Nell'area a destra, fai clic sul pulsante "Open Auth Settings" dopo "Need to configure authentication?".

5. Fai clic su "Quick OAuth Flow" e autorizza nella schermata OAuth.

6. Segui i passaggi nella sezione "OAuth Flow Progress" dell'inspector e fai clic su "Continue" fino a raggiungere "Authentication complete".

7. Copia il valore access_token.

8. Incollalo nel campo authorization_token nella configurazione del tuo server MCP.

Utilizzo del token di accesso

Una volta ottenuto un token di accesso utilizzando uno dei flussi OAuth precedenti, puoi utilizzarlo nella configurazione del tuo server MCP:

{
  "mcp_servers": [
    {
      "type": "url",
      "url": "https://example-server.modelcontextprotocol.io/sse",
      "name": "authenticated-server",
      "authorization_token": "YOUR_ACCESS_TOKEN_HERE"
    }
  ]
}

Per spiegazioni dettagliate del flusso OAuth, consulta la sezione Authorization nella specifica MCP.

Helper MCP lato client (TypeScript)

Se gestisci la tua connessione client MCP (ad esempio, con server stdio locali, prompt MCP o risorse MCP), l'SDK TypeScript fornisce funzioni helper che convertono tra i tipi MCP e i tipi della Claude API. Questo elimina il codice di conversione manuale quando si utilizza l'SDK MCP insieme all'SDK Anthropic.

Installazione

Installa sia l'SDK Anthropic che l'SDK MCP:

npm install @anthropic-ai/sdk @modelcontextprotocol/sdk

Helper disponibili

Importa gli helper dal namespace beta:

import {
  mcpTools,
  mcpMessages,
  mcpResourceToContent,
  mcpResourceToFile
} from "@anthropic-ai/sdk/helpers/beta/mcp";

Usa gli strumenti MCP

Converti gli strumenti MCP per l'uso con il tool runner dell'SDK, che gestisce automaticamente l'esecuzione degli strumenti:

import { mcpTools } from "@anthropic-ai/sdk/helpers/beta/mcp";
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

const anthropic = new Anthropic();

// Connettiti a un server MCP
const transport = new StdioClientTransport({ command: "mcp-server", args: [] });
const mcpClient = new Client({ name: "my-client", version: "1.0.0" });
await mcpClient.connect(transport);

// Elenca gli strumenti e convertili per l'API di Claude
const { tools } = await mcpClient.listTools();
const finalMessage = await anthropic.beta.messages.toolRunner({
  model: "claude-opus-4-8",
  max_tokens: 1024,
  messages: [{ role: "user", content: "What tools do you have available?" }],
  tools: mcpTools(tools, mcpClient)
});

console.log(finalMessage);

Usa i prompt MCP

Converti i messaggi di prompt MCP nel formato dei messaggi della Claude API:

import { mcpMessages } from "@anthropic-ai/sdk/helpers/beta/mcp";

const { messages } = await mcpClient.getPrompt({ name: "my-prompt" });
const response = await anthropic.beta.messages.create({
  model: "claude-opus-4-8",
  max_tokens: 1024,
  messages: mcpMessages(messages)
});

console.log(response);

Usa le risorse MCP

Converti le risorse MCP in blocchi di contenuto da includere nei messaggi, o in oggetti file per il caricamento:

import { mcpResourceToContent, mcpResourceToFile } from "@anthropic-ai/sdk/helpers/beta/mcp";

// Come blocco di contenuto in un messaggio
const resource = await mcpClient.readResource({ uri: "file:///path/to/doc.txt" });
await anthropic.beta.messages.create({
  model: "claude-opus-4-8",
  max_tokens: 1024,
  messages: [
    {
      role: "user",
      content: [
        mcpResourceToContent(resource),
        { type: "text", text: "Summarize this document" }
      ]
    }
  ]
});

// Come caricamento di file
const fileResource = await mcpClient.readResource({ uri: "file:///path/to/data.json" });
await anthropic.beta.files.upload({ file: mcpResourceToFile(fileResource) });

Gestione degli errori

Le funzioni di conversione generano UnsupportedMCPValueError se un valore MCP non è supportato dalla Claude API. Questo può accadere con tipi di contenuto non supportati, tipi MIME o link a risorse non HTTP.

Richieste batch

Puoi includere mcp_servers nelle richieste della Message Batches API. Le chiamate agli strumenti MCP tramite la Batches API hanno lo stesso prezzo di quelle nelle normali richieste della Messages API.

Conservazione dei dati

Il connettore MCP non è coperto dagli accordi ZDR. I dati scambiati con i server MCP, incluse le definizioni degli strumenti e i risultati di esecuzione, vengono conservati secondo la politica standard di conservazione dei dati di Anthropic.

Per l'idoneità ZDR su tutte le funzionalità, consulta API e conservazione dei dati.

Guida alla migrazione

Se stai utilizzando l'header beta deprecato mcp-client-2025-04-04, segui questa guida per migrare alla nuova versione.

Modifiche principali

1. Nuovo header beta: Cambia da mcp-client-2025-04-04 a mcp-client-2025-11-20
2. Configurazione degli strumenti spostata: La configurazione degli strumenti ora risiede nell'array tools come oggetti MCPToolset, non nella definizione del server MCP
3. Configurazione più flessibile: Il nuovo pattern supporta allowlist, denylist e configurazione per singolo strumento

Passaggi di migrazione

Prima (deprecato):

{
  "model": "claude-opus-4-8",
  "max_tokens": 1000,
  "messages": [
    // ...
  ],
  "mcp_servers": [
    {
      "type": "url",
      "url": "https://mcp.example.com/sse",
      "name": "example-mcp",
      "authorization_token": "YOUR_TOKEN",
      "tool_configuration": {
        "enabled": true,
        "allowed_tools": ["tool1", "tool2"]
      }
    }
  ]
}

Dopo (corrente):

{
  "model": "claude-opus-4-8",
  "max_tokens": 1000,
  "messages": [
    // ...
  ],
  "mcp_servers": [
    {
      "type": "url",
      "url": "https://mcp.example.com/sse",
      "name": "example-mcp",
      "authorization_token": "YOUR_TOKEN"
    }
  ],
  "tools": [
    {
      "type": "mcp_toolset",
      "mcp_server_name": "example-mcp",
      "default_config": {
        "enabled": false
      },
      "configs": {
        "tool1": {
          "enabled": true
        },
        "tool2": {
          "enabled": true
        }
      }
    }
  ]
}

Pattern di migrazione comuni

Versione deprecata: mcp-client-2025-04-04

La versione precedente del connettore MCP includeva la configurazione degli strumenti direttamente nella definizione del server MCP:

{
  "mcp_servers": [
    {
      "type": "url",
      "url": "https://example-server.modelcontextprotocol.io/sse",
      "name": "example-mcp",
      "authorization_token": "YOUR_TOKEN",
      "tool_configuration": {
        "enabled": true,
        "allowed_tools": ["example_tool_1", "example_tool_2"]
      }
    }
  ]
}

Descrizione dei campi deprecati