La funzionalità del connettore Model Context Protocol (MCP) di Claude ti consente di connetterti direttamente ai server MCP remoti 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 a 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

  • Delle funzionalità della specifica MCP, attualmente sono supportate solo le chiamate agli strumenti.
  • Il server deve essere esposto pubblicamente tramite HTTP. I server STDIO locali non possono essere collegati 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 all’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"
}

​
Descrizione dei campi

ProprietàTipoObbligatorioDescrizione
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 per il modello.
tool_configurationobjectNoConfigura l’utilizzo degli strumenti
tool_configuration.enabledbooleanNoSe abilitare gli strumenti da questo server (predefinito: true)
tool_configuration.allowed_toolsarrayNoElenco 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 gli 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": "Hello"
    }
  ]
}

​
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 versione 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 quando necessario.

​
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 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 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 sul flusso OAuth, consulta la sezione Autorizzazione nella specifica MCP.