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.

Questa funzionalità richiede l’header beta: "anthropic-beta": "mcp-client-2025-04-04"

​
Caratteristiche principali

  • Integrazione API diretta: Connettiti ai server MCP senza implementare un client MCP
  • Supporto per chiamate di strumenti: Accedi agli strumenti MCP tramite l’API Messages
  • 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 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 attualmente non è supportato su Amazon Bedrock e Google Vertex.

​
Utilizzo del connettore MCP nell’API Messages

Per connetterti a un server MCP remoto, includi il parametro mcp_servers nella tua richiesta API Messages:

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-04-04" \
  -d '{
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1000,
    "messages": [{"role": "user", "content": "Quali strumenti hai a disposizione?"}],
    "mcp_servers": [
      {
        "type": "url",
        "url": "https://example-server.modelcontextprotocol.io/sse",
        "name": "example-mcp",
        "authorization_token": "YOUR_TOKEN"
      }
    ]
  }'

​
Configurazione del server MCP

Ogni server MCP nell’array mcp_servers supporta la seguente configurazione:

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

​
Descrizioni dei campi

ProprietàTipoRichiestoDescrizione
typestringSìAttualmente è supportato solo “url”
urlstringSìL’URL del server MCP. Deve iniziare con https://
namestringSìUn identificatore univoco per questo server MCP. Sarà utilizzato nei blocchi mcp_tool_call per identificare il server e per disambiguare gli strumenti al modello.
tool_configurationobjectNoConfigura l’utilizzo degli strumenti
tool_configuration.enabledbooleanNoSe abilitare gli strumenti da questo server (predefinito: true)
tool_configuration.allowed_toolsarrayNoLista per limitare gli strumenti da consentire (per impostazione predefinita, tutti gli strumenti sono consentiti)
authorization_tokenstringNoToken di autorizzazione OAuth se richiesto dal server MCP. Vedi specifica MCP.

​
Tipi di contenuto della risposta

Quando Claude utilizza strumenti MCP, la risposta includerà due nuovi tipi di blocchi di contenuto:

​
Blocco di utilizzo strumento MCP

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

​
Blocco di risultato strumento MCP

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

​
Server MCP multipli

Puoi connetterti a più server MCP includendo più oggetti nell’array mcp_servers:

{
  "model": "claude-sonnet-4-20250514",
  "max_tokens": 1000,
  "messages": [
    {
      "role": "user",
      "content": "Usa strumenti sia da mcp-server-1 che da mcp-server-2 per completare questo compito"
    }
  ],
  "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"
    }
  ]
}

​
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 sono tenuti a gestire il flusso OAuth e ottenere il token di accesso prima di effettuare la chiamata API, così come 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 per scopi 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 “Transport type”, seleziona “SSE” o “Streamable HTTP”.

  3. Inserisci l’URL del server MCP.

  4. Nell’area di destra, clicca sul pulsante “Open Auth Settings” dopo “Need to configure authentication?”.

  5. Clicca “Quick OAuth Flow” e autorizza sulla schermata OAuth.

  6. Segui i passaggi nella sezione “OAuth Flow Progress” dell’ispettore e clicca “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.