Connettore MCP

La funzionalità connettore "Model Context Protocol", o MCP, di Claude ti consente di connetterti a server MCP remoti direttamente dalla Messages API senza un client MCP separato.

Caratteristiche principali

• Integrazione diretta con l'API: Connettiti ai server MCP senza implementare un client MCP
• Supporto per la chiamata di strumenti: Accedi agli strumenti MCP tramite la Messages API
• Configurazione flessibile degli strumenti: Abilita tutti gli strumenti, inserisci in allowlist strumenti specifici o in denylist 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

Quando Claude usa gli strumenti MCP

Una volta connesso un server MCP, Claude chiama i suoi strumenti quando la richiesta dell'utente corrisponde alla capacità descritta di uno strumento, sia esplicitamente ("cerca in Jira i bug aperti") sia implicitamente ("cosa sta bloccando il rilascio?" con un server Jira collegato).

Claude non chiama uno strumento MCP per domande di conoscenza generale su un servizio connesso. Chiedere "come funzionano i database di Notion?" con un server Notion collegato riceve una risposta diretta; chiedere "cosa c'è nel mio database Projects?" attiva lo strumento.

Puoi orientare la propensione di Claude a chiamare gli strumenti MCP tramite il tuo "system prompt" (prompt di sistema). Consulta Quando Claude usa gli strumenti per indicazioni generali ed esempi di formulazione.

Limitazioni

• Dell'insieme di funzionalità della specifica MCP, attualmente sono supportate solo le chiamate di strumenti.
• Il server deve essere esposto pubblicamente tramite HTTP (supporta sia il trasporto Streamable HTTP sia SSE). I server STDIO locali non possono essere connessi direttamente.

Utilizzo del connettore MCP nella Messages API

Il connettore MCP utilizza due componenti:

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

Esempio di base

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

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-5",
    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"}],
    betas=["mcp-client-2025-11-20"],
)

print(response)

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

Descrizione dei campi

Configurazione del toolset 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
    }
  }
}

Descrizione dei campi

Opzioni di configurazione degli strumenti

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

Per l'elenco completo degli strumenti forniti da Anthropic e delle proprietà opzionali come defer_loading, consulta il Riferimento degli strumenti. Per cercare all'interno di grandi insiemi di strumenti, consulta lo strumento di ricerca strumenti.

Unione delle configurazioni

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

1. Impostazioni specifiche dello strumento in configs
2. default_config a livello di set
3. Valori predefiniti 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 (predefinito di sistema), defer_loading: true (da default_config)

Pattern di configurazione comuni

Abilitare tutti gli strumenti con la configurazione predefinita

Il pattern più semplice: abilita tutti gli strumenti di un server:

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

Allowlist: abilitare 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
    }
  }
}

Denylist: disabilitare strumenti specifici

Abilita tutti gli strumenti per impostazione predefinita, quindi disabilita esplicitamente gli strumenti indesiderati. Inserire in denylist gli strumenti di scrittura o distruttivi è consigliato quando si creano assistenti di sola lettura, o quando si desidera un passaggio di conferma umana prima delle modifiche di stato:

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

Misto: allowlist con configurazione per singolo strumento

Combina l'allowlist con una 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
• Toolset 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 nel backend ma non viene restituito alcun errore (i server MCP possono avere disponibilità dinamica degli strumenti)

Tipi di contenuto della risposta

Quando Claude usa gli strumenti MCP, la risposta include due nuovi tipi di blocchi di contenuto:

Blocco MCP tool use

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

Blocco MCP tool result

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

Con molti strumenti disponibili, Claude seleziona in base ai nomi e alle descrizioni degli strumenti. Descrizioni degli strumenti chiare e specifiche migliorano l'accuratezza della selezione. Per grandi insiemi di strumenti (decine di strumenti su diversi server), considera di abilitare defer_loading con lo strumento di ricerca strumenti in modo che per ogni query vengano presentati solo gli strumenti pertinenti.

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. Ci si aspetta che i consumatori dell'API gestiscano il flusso OAuth e ottengano il token di accesso prima di effettuare la chiamata API, e che aggiornino il token secondo necessità.

Ottenere un token di accesso per i test

L'MCP inspector può guidarti attraverso il processo di ottenimento di un token di accesso a scopo di test.

1. Esegui l'inspector con il seguente comando. È necessario avere Node.js installato sulla tua macchina.

   npx @modelcontextprotocol/inspector

   

2. Nella barra laterale a sinistra, per Transport type, seleziona SSE oppure Streamable HTTP.

3. Inserisci l'URL del server MCP.

4. Nell'area a destra, fai clic su 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 di access_token.

8. Incollalo nel campo authorization_token della configurazione del tuo server MCP.

Utilizzo del token di accesso

Una volta ottenuto un token di accesso utilizzando uno dei flussi OAuth precedenti, puoi usarlo 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 Authorization nella specifica MCP.

Helper MCP lato client

Se gestisci la tua connessione client MCP (ad esempio, con server stdio locali, prompt MCP o risorse MCP), gli SDK forniscono funzioni helper che convertono tra i tipi MCP e i tipi della Claude API. Questo elimina il codice di conversione manuale quando si utilizza un SDK MCP per il proprio linguaggio (ad esempio, il TypeScript MCP SDK) insieme all'SDK Anthropic.

Installazione

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

pip install "anthropic[mcp]"

Helper disponibili

Importa gli helper per il tuo linguaggio:

from anthropic.lib.tools.mcp import (
    async_mcp_tool,
    mcp_message,
    mcp_resource_to_content,
    mcp_resource_to_file,
)

I nomi degli helper e le firme esatte seguono le convenzioni di ciascun linguaggio; questa tabella mostra le forme TypeScript:

Usare gli strumenti MCP

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

from anthropic.lib.tools.mcp import async_mcp_tool
from mcp import ClientSession
from mcp.client.stdio import StdioServerParameters, stdio_client

client = AsyncAnthropic()


async def main() -> None:
    # Connettiti a un server MCP
    server_params = StdioServerParameters(command="mcp-server")
    async with stdio_client(server_params) as (read, write):
        async with ClientSession(read, write) as mcp_client:
            await mcp_client.initialize()

            # Elenca gli strumenti e convertili per l'API di Claude
            tools_result = await mcp_client.list_tools()
            runner = client.beta.messages.tool_runner(
                model="claude-opus-5",
                max_tokens=1024,
                messages=[
                    {"role": "user", "content": "What tools do you have available?"},
                ],
                tools=[async_mcp_tool(tool, mcp_client) for tool in tools_result.tools],
            )

            final_message = await runner.until_done()
            print(final_message)


asyncio.run(main())

Usare i prompt MCP

Converti i messaggi dei prompt MCP nel formato messaggio della Claude API:

from anthropic.lib.tools.mcp import mcp_message

prompt = await mcp_client.get_prompt(name="my-prompt")
response = await client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    messages=[mcp_message(message) for message in prompt.messages],
)

print(response)

Usare le risorse MCP

Converti le risorse MCP in blocchi di contenuto da includere nei messaggi, oppure in oggetti file per il caricamento:

from anthropic.lib.tools.mcp import (
    mcp_resource_to_content,
    mcp_resource_to_file,
)

# Come blocco di contenuto in un messaggio
resource = await mcp_client.read_resource(uri="file:///path/to/doc.txt")
response = await client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                mcp_resource_to_content(resource),
                {"type": "text", "text": "Summarize this document"},
            ],
        }
    ],
)
print(response)

# Come caricamento di file
file_resource = await mcp_client.read_resource(
    uri="file:///path/to/data.json",
)
uploaded = await client.files.upload(
    file=mcp_resource_to_file(file_resource),
)
print(uploaded.id)

Gestione degli errori

Le funzioni di conversione lanciano UnsupportedMCPValueError se un valore MCP non è supportato dalla Claude API (in Go, gli helper restituiscono un UnsupportedValueError; in Java e C#, lanciano AnthropicInvalidDataException). Questo può accadere con tipi di contenuto, tipi MIME o link a risorse non supportati (risolvi i link a risorse con il tuo client MCP prima della conversione).

Richieste batch

Puoi includere mcp_servers nelle richieste della Message Batches API. Le chiamate di strumenti MCP tramite la Batches API hanno lo stesso prezzo di quelle nelle normali richieste della Messages API.

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 di esecuzione, vengono conservati secondo la politica standard di conservazione dei dati di Anthropic.

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

Guida alla migrazione

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

Modifiche principali

1. Nuovo header beta: Passa 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 allowlist, denylist e configurazione per singolo strumento

Passaggi di migrazione

Prima (deprecato):

{
  "model": "claude-opus-5",
  "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 (attuale):

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

Descrizione dei campi deprecati

Compatibility