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 ai server MCP senza implementare un client MCP
• Supporto per chiamate di strumenti: Accedi agli strumenti MCP attraverso l'API Messages
• Autenticazione OAuth: Supporto per token OAuth Bearer per server autenticati
• Server multipli: Connettiti a più server MCP in una singola richiesta

Limitazioni

• Del set 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 Streamable HTTP 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-5",
    "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"
      }
    ]
  }'

import { Anthropic } from '@anthropic-ai/sdk';

const anthropic = new Anthropic();

const response = await anthropic.beta.messages.create({
  model: "claude-sonnet-4-5",
  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",
    },
  ],
  betas: ["mcp-client-2025-04-04"],
});

import anthropic

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1000,
    messages=[{
        "role": "user",
        "content": "Quali strumenti hai a disposizione?"
    }],
    mcp_servers=[{
        "type": "url",
        "url": "https://mcp.example.com/sse",
        "name": "example-mcp",
        "authorization_token": "YOUR_TOKEN"
    }],
    betas=["mcp-client-2025-04-04"]
)

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

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 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-5",
  "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 "Tipo di trasporto", seleziona "SSE" o "Streamable HTTP".

3. Inserisci l'URL del server MCP.

4. Nell'area di destra, clicca sul pulsante "Apri impostazioni di autenticazione" dopo "Hai bisogno di configurare l'autenticazione?".

5. Clicca "Flusso OAuth rapido" e autorizza sulla schermata OAuth.

6. Segui i passaggi nella sezione "Progresso del flusso OAuth" dell'ispettore e clicca "Continua" fino a raggiungere "Autenticazione completata".

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.