Connettore MCP

La funzionalità del connettore Model Context Protocol (MCP) di Claude ti consente di connetterti a server MCP remoti direttamente dall'API Messages senza un client MCP separato.

Funzionalità principali

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

Limitazioni

• Del set di funzionalità della specifica MCP, sono attualmente supportate solo le chiamate agli strumenti.
• Il server deve essere esposto pubblicamente tramite HTTP (supporta sia i trasporti Streamable HTTP che SSE). I server STDIO locali non possono essere connessi direttamente.
• Il connettore MCP non è attualmente supportato su Amazon Bedrock e Google Vertex.

Utilizzo del connettore MCP nell'API Messages

Il connettore MCP utilizza due componenti:

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

Esempio di base

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

curl https://api.anthropic.com/v1/messages \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: mcp-client-2025-11-20" \
  -d '{
    "model": "claude-opus-4-6",
    "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"
      }
    ]
  }'

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"
}

Descrizioni dei campi

Configurazione del set di strumenti MCP

L'MCPToolset si trova 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
    }
  }
}

Descrizioni dei campi

Opzioni di configurazione degli strumenti

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

Unione delle configurazioni

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

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

Esempio:

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

Risulta in:

• search_events: enabled: false (da configs), defer_loading: true (da default_config)
• Tutti gli altri strumenti: enabled: true (impostazione predefinita 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 da un server:

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

Lista consentiti - 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
    }
  }
}

Lista negata - Disabilita strumenti specifici

Abilita tutti gli strumenti per impostazione predefinita, quindi disabilita esplicitamente gli strumenti indesiderati:

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

Misto - Lista consentiti con configurazione per strumento

Combina la lista consentiti con la 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
• Set di strumenti univoco per server: Ogni server MCP può essere referenziato solo da un 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 includerà due nuovi tipi di blocchi di contenuto:

Blocco di utilizzo dello strumento MCP

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

Blocco del risultato dello strumento MCP

{
  "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-6",
  "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
      }
    }
  ]
}

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, nonché aggiornare il token secondo necessità.

Ottenere un token di accesso per i test

L'inspector MCP può guidarti nel processo di ottenimento di un token di accesso per scopi di test.

1. Esegui l'inspector con il seguente comando. È necessario avere Node.js installato sul tuo computer.

   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 sopra descritti, 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 Autorizzazione 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), il TypeScript SDK fornisce funzioni helper che convertono tra i tipi MCP e i tipi dell'API Claude. Questo elimina il codice di conversione manuale quando si utilizza l'MCP SDK insieme all'Anthropic SDK.

Installazione

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

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

Helper disponibili

Importa gli helper dallo spazio dei nomi beta:

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

Utilizzo degli strumenti MCP

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

import Anthropic from "@anthropic-ai/sdk";
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();

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

// List tools and convert them for the Claude API
const { tools } = await mcpClient.listTools();
const runner = await anthropic.beta.messages.toolRunner({
  model: "claude-sonnet-4-6",
  max_tokens: 1024,
  messages: [{ role: "user", content: "What tools do you have available?" }],
  tools: mcpTools(tools, mcpClient)
});

Utilizzo dei prompt MCP

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

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-sonnet-4-6",
  max_tokens: 1024,
  messages: mcpMessages(messages)
});

Utilizzo delle 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";

// As a content block in a message
const resource = await mcpClient.readResource({ uri: "file:///path/to/doc.txt" });
await anthropic.beta.messages.create({
  model: "claude-sonnet-4-6",
  max_tokens: 1024,
  messages: [
    {
      role: "user",
      content: [
        mcpResourceToContent(resource),
        { type: "text", text: "Summarize this document" }
      ]
    }
  ]
});

// As a file upload
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 dall'API Claude. Ciò può accadere con tipi di contenuto non supportati, tipi MIME o link di risorse non HTTP.

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 dell'esecuzione, vengono conservati in conformità con la politica di conservazione dei dati standard di Anthropic.

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

Guida alla migrazione

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

Modifiche principali

1. Nuova intestazione beta: Cambia da mcp-client-2025-04-04 a mcp-client-2025-11-20
2. Configurazione degli strumenti spostata: La configurazione degli strumenti ora si trova nell'array tools come oggetti MCPToolset, non nella definizione del server MCP
3. Configurazione più flessibile: Il nuovo pattern supporta la lista consentiti, la lista negata e la configurazione per singolo strumento

Passaggi di migrazione

Prima (deprecato):

{
  "model": "claude-opus-4-6",
  "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-6",
  "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"]
      }
    }
  ]
}

Descrizioni dei campi deprecati