Connettore MCP

La funzionalità del 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.



Funzionalità principali

• Integrazione diretta con l'API: Connettiti a server MCP senza implementare un client MCP
• Supporto per le chiamate agli strumenti: Accedi agli strumenti MCP tramite la Messages API
• Configurazione flessibile degli strumenti: Abilita tutti gli strumenti, crea una allowlist di strumenti specifici o una denylist di strumenti indesiderati
• Configurazione per singolo strumento: Configura singoli strumenti con impostazioni personalizzate
• Autenticazione OAuth: Supporto per token OAuth Bearer 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 a una capacità descritta di uno strumento, sia esplicitamente ("cerca su 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 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 agli strumenti.
• Il server deve essere esposto pubblicamente tramite HTTP (supporta sia il trasporto Streamable HTTP che 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. MCP Toolset (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 dell'MCP toolset

L'MCPToolset risiede 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 che 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 la ricerca in set di strumenti di grandi dimensioni, consulta lo strumento Tool search.



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

Risultato:

• 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 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 chiare e specifiche degli strumenti migliorano l'accuratezza della selezione. Per set di strumenti di grandi dimensioni (decine di strumenti su diversi server), considera di abilitare defer_loading con lo strumento Tool search in modo che vengano mostrati solo gli strumenti rilevanti per ogni query.



Autenticazione

Per i server MCP che richiedono l'autenticazione OAuth, dovrai ottenere un access token. La 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 l'access token prima di effettuare la chiamata API, e aggiornare il token quando necessario.



Ottenere un access token per i test

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

1. Esegui l'inspector con il seguente comando. Devi avere 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'inspector 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 dell'access token

Una volta ottenuto un access token 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, consulta la 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 dell'API di Claude. Questo elimina il codice di conversione manuale quando si utilizza un SDK MCP per il tuo linguaggio (ad esempio, il TypeScript MCP SDK) insieme all'SDK di Anthropic.



Installazione

Installa sia l'SDK di Anthropic che 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 l'uso 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 di prompt MCP nel formato di messaggio dell'API di Claude:

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, o in oggetti file per l'upload:

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

# As a content block in a message
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)

# As a file upload
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 dall'API di Claude (in Go, gli helper restituiscono un UnsupportedValueError; in Java e C#, lanciano AnthropicInvalidDataException). Questo può accadere con tipi di contenuto non supportati, tipi MIME o link a risorse (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 agli 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 su 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: Cambia da mcp-client-2025-04-04 a mcp-client-2025-11-20
2. Configurazione degli strumenti spostata: La configurazione degli strumenti ora risiede 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