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.

Caratteristiche principali

• Integrazione API diretta: Connettiti a server MCP senza implementare un client MCP
• Supporto per le chiamate di strumenti: Accedi agli strumenti MCP tramite l'API Messages
• Configurazione flessibile degli strumenti: Abilita tutti gli strumenti, crea una lista di strumenti specifici o nega gli strumenti indesiderati
• Configurazione per singolo strumento: Configura 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

• Della serie di funzionalità della specifica MCP, attualmente sono supportate solo le chiamate di strumenti.
• Il server deve essere esposto pubblicamente tramite HTTP (supporta sia i trasporti HTTP Streamable 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 della 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 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 della 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

MCPToolset si trova nell'array tools e configura quali strumenti dal 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 dello strumento

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

Fusione della configurazione

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

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

Esempio:

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

Risultati in:

• search_events: enabled: false (da configs), defer_loading: true (da default_config)
• Tutti gli altri strumenti: enabled: true (impostazione predefinita del sistema), defer_loading: true (da default_config)

Modelli di configurazione comuni

Abilita tutti gli strumenti con configurazione predefinita

Il modello più semplice - abilita tutti gli strumenti da un server:

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

Lista di autorizzazione - 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 di negazione - 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 di autorizzazione con configurazione per singolo strumento

Combina la lista di autorizzazione con 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 convalida

L'API applica queste regole di convalida:

• 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 da un solo MCPToolset
• Nomi di strumenti sconosciuti: Se un nome di strumento in configs non esiste sul server MCP, viene registrato un avviso di backend ma non viene restituito alcun errore (i server MCP possono avere disponibilità di strumenti dinamica)

Tipi di contenuto della risposta

Quando Claude utilizza strumenti MCP, la risposta includerà due nuovi tipi di blocco 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 di 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. Il beta del connettore MCP supporta il passaggio di un parametro authorization_token nella definizione del server MCP. I consumatori di 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'ispettore MCP può guidarti attraverso il processo di ottenimento di un token di accesso a scopo di test.

1. Esegui l'ispettore con il seguente comando. Hai bisogno di Node.js installato sulla tua macchina.

   npx @modelcontextprotocol/inspector

2. Nella barra laterale a sinistra, per "Tipo di trasporto", 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'ispettore 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, 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, fai riferimento alla 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), l'SDK TypeScript fornisce funzioni helper che convertono tra tipi MCP e tipi API Claude. Ciò 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 dallo spazio dei nomi beta:

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

Utilizza gli strumenti MCP

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

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

Utilizza i prompt MCP

Converti i messaggi di prompt MCP nel formato di messaggio 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)
});

Utilizza 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";

// 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 lanciano UnsupportedMCPValueError se un valore MCP non è supportato dall'API Claude. Questo può accadere con tipi di contenuto non supportati, tipi MIME o link di risorse non HTTP.

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 dello strumento spostata: La configurazione dello strumento ora si trova nell'array tools come oggetti MCPToolset, non nella definizione del server MCP
3. Configurazione più flessibile: Il nuovo modello supporta liste di autorizzazione, liste di negazione e 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
        }
      }
    }
  ]
}

Modelli di migrazione comuni

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

La versione precedente del connettore MCP includeva la configurazione dello strumento 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