--- title: Connettore MCP url: https://platform.claude.com/docs/it/managed-agents/mcp-connector description: Collega i server MCP ai tuoi agenti per accedere a strumenti e fonti di dati esterni. featureMetadata: topic: title: Managed Agents url: https://platform.claude.com/docs/en/managed-agents/overview status: beta betaHeader: managed-agents-2026-04-01 --- Claude Managed Agents supporta la connessione di server [Model Context Protocol (MCP)](https://modelcontextprotocol.io) ai tuoi agenti. Questo dà all'agente accesso a strumenti esterni, fonti di dati e servizi attraverso un protocollo standardizzato. La configurazione MCP è suddivisa in due passaggi: 1. **La creazione dell'agente** dichiara a quali server MCP l'agente si connette, per nome e URL. 2. **La creazione della sessione** fornisce l'autenticazione per quei server facendo riferimento a un vault pre-registrato (vedi [Autenticazione con i vault](https://platform.claude.com/docs/it/managed-agents/vaults)). Questa separazione mantiene i segreti fuori dalle definizioni riutilizzabili degli agenti, consentendo al contempo a ogni sessione di autenticarsi con le proprie credenziali. ## Dichiara i server MCP sull'agente Specifica i server MCP nell'array `mcp_servers` (java, php: `mcpServers`; csharp: `McpServers`; go: `MCPServers`) durante la creazione di un agente. Ogni server richiede un `type` (csharp, go: `Type`), un `name` (csharp, go: `Name`) univoco e un `url` (csharp: `Url`; go: `URL`). In questa fase non vengono forniti token di autenticazione. Ogni server dichiarato richiede anche una voce `mcp_toolset` corrispondente nell'array `tools` (csharp, go: `Tools`). Il `mcp_server_name` (java, php: `mcpServerName`; csharp: `McpServerName`; go: `MCPServerName`) del toolset deve corrispondere al `name` (csharp, go: `Name`) del server. ```bash cURL curl -sS --fail-with-body https://api.anthropic.com/v1/agents \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "anthropic-beta: managed-agents-2026-04-01" \ -H "content-type: application/json" \ -d '{ "name": "GitHub Assistant", "model": "claude-opus-5-5", "mcp_servers": [ { "type": "url", "name": "github", "url": "https://api.githubcopilot.com/mcp/" } ], "tools": [ {"type": "agent_toolset_20260401"}, {"type": "mcp_toolset", "mcp_server_name": "github"} ] }' ``` ```bash CLI ant apply github-assistant.md ``` ```markdown --- name: GitHub Assistant model: claude-opus-5-5 mcp_servers: - type: url name: github url: https://api.githubcopilot.com/mcp/ tools: - type: agent_toolset_20260401 - type: mcp_toolset mcp_server_name: github --- ``` ```python Python agent = client.beta.agents.create( name="GitHub Assistant", model="claude-opus-5-5", mcp_servers=[ { "type": "url", "name": "github", "url": "https://api.githubcopilot.com/mcp/", }, ], tools=[ {"type": "agent_toolset_20260401"}, {"type": "mcp_toolset", "mcp_server_name": "github"}, ], ) ``` ```typescript TypeScript const agent = await client.beta.agents.create({ name: "GitHub Assistant", model: "claude-opus-5-5", mcp_servers: [ { type: "url", name: "github", url: "https://api.githubcopilot.com/mcp/" } ], tools: [ { type: "agent_toolset_20260401" }, { type: "mcp_toolset", mcp_server_name: "github" } ] }); ``` ```csharp C# var agent = await client.Beta.Agents.Create(new() { Name = "GitHub Assistant", Model = BetaManagedAgentsModel.ClaudeOpus5_5, McpServers = [ new() { Type = "url", Name = "github", Url = "https://api.githubcopilot.com/mcp/" }, ], Tools = [ new BetaManagedAgentsAgentToolset20260401Params { Type = "agent_toolset_20260401", }, new BetaManagedAgentsMcpToolsetParams { Type = "mcp_toolset", McpServerName = "github" }, ], }); ``` ```go Go agent, err := client.Beta.Agents.New(ctx, anthropic.BetaAgentNewParams{ Name: "GitHub Assistant", Model: anthropic.BetaManagedAgentsModelConfigParams{ ID: anthropic.BetaManagedAgentsModelClaudeOpus5_5, }, MCPServers: []anthropic.BetaManagedAgentsURLMCPServerParams{{ Type: anthropic.BetaManagedAgentsURLMCPServerParamsTypeURL, Name: "github", URL: "https://api.githubcopilot.com/mcp/", }}, Tools: []anthropic.BetaAgentNewParamsToolUnion{ { OfAgentToolset20260401: &anthropic.BetaManagedAgentsAgentToolset20260401Params{ Type: anthropic.BetaManagedAgentsAgentToolset20260401ParamsTypeAgentToolset20260401, }, }, { OfMCPToolset: &anthropic.BetaManagedAgentsMCPToolsetParams{ Type: anthropic.BetaManagedAgentsMCPToolsetParamsTypeMCPToolset, MCPServerName: "github", }, }, }, }) if err != nil { panic(err) } ``` ```java Java var agent = client.beta().agents().create( AgentCreateParams.builder() .name("GitHub Assistant") .model(BetaManagedAgentsModel.CLAUDE_OPUS_5_5) .addMcpServer( BetaManagedAgentsUrlMcpServerParams.builder() .type(BetaManagedAgentsUrlMcpServerParams.Type.URL) .name("github") .url("https://api.githubcopilot.com/mcp/") .build() ) .addTool( BetaManagedAgentsAgentToolset20260401Params.builder() .type(BetaManagedAgentsAgentToolset20260401Params.Type.AGENT_TOOLSET_20260401) .build() ) .addTool( BetaManagedAgentsMcpToolsetParams.builder() .type(BetaManagedAgentsMcpToolsetParams.Type.MCP_TOOLSET) .mcpServerName("github") .build() ) .build() ); ``` ```php PHP $agent = $client->beta->agents->create( name: 'GitHub Assistant', model: 'claude-opus-5-5', mcpServers: [ BetaManagedAgentsURLMCPServerParams::with( type: 'url', name: 'github', url: 'https://api.githubcopilot.com/mcp/', ), ], tools: [ BetaManagedAgentsAgentToolset20260401Params::with( type: 'agent_toolset_20260401', ), BetaManagedAgentsMCPToolsetParams::with( type: 'mcp_toolset', mcpServerName: 'github', ), ], ); ``` ```ruby Ruby agent = client.beta.agents.create( name: "GitHub Assistant", model: "claude-opus-5-5", mcp_servers: [ { type: "url", name: "github", url: "https://api.githubcopilot.com/mcp/" } ], tools: [ {type: "agent_toolset_20260401"}, {type: "mcp_toolset", mcp_server_name: "github"} ] ) ``` Il toolset MCP ha come impostazione predefinita una policy di autorizzazione `always_ask`, che richiede l'approvazione dell'utente prima di ogni chiamata a uno strumento. Consulta le [policy di autorizzazione](https://platform.claude.com/docs/it/managed-agents/permission-policies) per configurare questo comportamento. ### Riferimento del campo `mcp_servers` Ogni voce nell'array `mcp_servers` (java, php: `mcpServers`; csharp: `McpServers`; go: `MCPServers`) definisce una connessione. | Campo | Descrizione | | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `type` (csharp, go: `Type`) | Obbligatorio. Deve essere `"url"`. | | `name` (csharp, go: `Name`) | Obbligatorio. Un nome univoco per questo server all'interno dell'agente (1–255 caratteri). Utilizzato come `mcp_server_name` (java, php: `mcpServerName`; csharp: `McpServerName`; go: `MCPServerName`) nell'array `tools` (csharp, go: `Tools`) e mostrato negli eventi degli strumenti MCP nel [flusso di eventi della sessione](https://platform.claude.com/docs/it/managed-agents/events-and-streaming). | | `url` (csharp: `Url`; go: `URL`) | Obbligatorio. L'endpoint del server MCP remoto (fino a 2.048 caratteri). Consulta [Tipi di server MCP supportati](https://platform.claude.com/docs/it/managed-agents/reference#supported-mcp-server-types) per i requisiti di trasporto. | Vincoli: * Un agente può dichiarare fino a 20 server MCP. I nomi dei server devono essere univoci all'interno dell'array. * Ogni voce di `mcp_servers` (java, php: `mcpServers`; csharp: `McpServers`; go: `MCPServers`) deve essere referenziata da un `mcp_toolset` nell'array `tools` (csharp, go: `Tools`), e ogni `mcp_toolset` deve fare riferimento a un server dichiarato. L'API rifiuta le definizioni di agenti con server non referenziati o toolset orfani. ## Configura quali strumenti MCP sono disponibili La voce `mcp_toolset` supporta un oggetto `default_config` (java, php: `defaultConfig`; csharp, go: `DefaultConfig`) e un array `configs` (csharp, go: `Configs`), applicati agli strumenti esposti dal server MCP. Ogni voce di `configs` (csharp, go: `Configs`) accetta solo `name` (csharp, go: `Name`), `enabled` (csharp, go: `Enabled`) e `permission_policy` (java, php: `permissionPolicy`; csharp, go: `PermissionPolicy`). A differenza delle voci nel toolset integrato dell'agente, le voci degli strumenti MCP non accettano un campo `type` (csharp, go: `Type`), e le [impostazioni web](https://platform.claude.com/docs/it/managed-agents/tools-web-restrictions#settings) disponibili su `web_search` e `web_fetch` non si applicano agli strumenti MCP. Il `name` (csharp, go: `Name`) in ogni voce di `configs` (csharp, go: `Configs`) è il nome semplice dello strumento così come riportato dal server. Per impostazione predefinita tutti gli strumenti esposti dal server MCP sono abilitati. Per abilitare solo strumenti specifici, imposta `default_config.enabled` su `false` e abilita esplicitamente gli strumenti che desideri: ```json { "type": "mcp_toolset", "mcp_server_name": "github", "default_config": { "enabled": false }, "configs": [ { "name": "get_issue", "enabled": true }, { "name": "list_issues", "enabled": true }, { "name": "add_issue_comment", "enabled": true } ] } ``` Questo schema è utile quando un server espone molti strumenti ma l'agente ne necessita solo alcuni, oppure quando vuoi che gli strumenti aggiunti dall'operatore del server restino disattivati finché non li hai esaminati. Per disabilitare strumenti specifici mantenendo abilitati gli altri, ometti `default_config` e imposta `enabled: false` sulle singole voci: ```json { "type": "mcp_toolset", "mcp_server_name": "github", "configs": [{ "name": "delete_repository", "enabled": false }] } ``` Consulta [configurazione del toolset](https://platform.claude.com/docs/it/managed-agents/tools#configuring-the-toolset) per lo schema generale `default_config` (java, php: `defaultConfig`; csharp, go: `DefaultConfig`) / `configs` (csharp, go: `Configs`), e [autorizzazioni del toolset MCP](https://platform.claude.com/docs/it/managed-agents/permission-policies#mcp-toolset-permissions) per impostare `permission_policy` (java, php: `permissionPolicy`; csharp, go: `PermissionPolicy`) sugli strumenti MCP e gestire le richieste di conferma. ### Gestione dell'output degli strumenti MCP Quando l'output di uno strumento MCP supera i 100.000 caratteri (circa 25.000 token), viene automaticamente scritto in un file nella sandbox. Il modello riceve un'anteprima troncata con il percorso del file e può leggere il contenuto completo da lì. ## Fornisci l'autenticazione alla creazione della sessione Quando avvii una sessione, passa `vault_ids` (java: `vaultIds`; php: `vaultIDs`; csharp: `VaultIds`; go: `VaultIDs`) per fornire le credenziali per i tuoi server MCP. I vault sono raccolte di credenziali che registri una sola volta e a cui fai riferimento tramite ID. Consulta [Autenticazione con i vault](https://platform.claude.com/docs/it/managed-agents/vaults) per sapere come creare vault e gestire le credenziali. Con un [ambiente](https://platform.claude.com/docs/it/managed-agents/environments#networking) `limited`, la creazione della sessione fallisce con un errore 400 quando l'agente dichiara un server MCP il cui host non è presente in `allowed_hosts` (java, php: `allowedHosts`; csharp, go: `AllowedHosts`). Impostare `allow_mcp_servers` (java: `allowMcpServers`; php: `allowMCPServers`; csharp: `AllowMcpServers`; go: `AllowMCPServers`) su `true` nella configurazione di rete dell'ambiente disattiva questo controllo. ```bash cURL curl -sS --fail-with-body https://api.anthropic.com/v1/sessions \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "anthropic-beta: managed-agents-2026-04-01" \ -H "content-type: application/json" \ -d '{ "agent": "'"$agent_id"'", "environment_id": "'"$environment_id"'", "vault_ids": ["'"$vault_id"'"] }' ``` ```bash CLI ant beta:sessions create \ --agent "$AGENT_ID" \ --environment-id "$ENVIRONMENT_ID" \ --vault-id "$VAULT_ID" ``` ```python Python session = client.beta.sessions.create( agent=agent.id, environment_id=environment.id, vault_ids=[vault.id], ) ``` ```typescript TypeScript const session = await client.beta.sessions.create({ agent: agent.id, environment_id: environment.id, vault_ids: [vault.id] }); ``` ```csharp C# var session = await client.Beta.Sessions.Create(new() { Agent = agent.ID, EnvironmentID = environment.ID, VaultIds = [vault.ID], }); ``` ```go Go session, err := client.Beta.Sessions.New(ctx, anthropic.BetaSessionNewParams{ Agent: anthropic.BetaSessionNewParamsAgentUnion{OfString: anthropic.String(agent.ID)}, EnvironmentID: environment.ID, VaultIDs: []string{vault.ID}, }) if err != nil { panic(err) } ``` ```java Java var session = client.beta().sessions().create( SessionCreateParams.builder() .agent(agent.id()) .environmentId(environment.id()) .addVaultId(vault.id()) .build() ); ``` ```php PHP $session = $client->beta->sessions->create( agent: $agent->id, environmentID: $environment->id, vaultIDs: [$vault->id], ); ``` ```ruby Ruby session = client.beta.sessions.create( agent: agent.id, environment_id: environment.id, vault_ids: [vault.id] ) ``` Le credenziali vengono associate tramite URL, quindi il vault deve contenere una credenziale il cui `mcp_server_url` (java: `mcpServerUrl`; php: `mcpServerURL`; csharp: `McpServerUrl`; go: `MCPServerURL`) si riferisca allo stesso server dell'`url` (csharp: `Url`; go: `URL`) dichiarato in `mcp_servers` (java, php: `mcpServers`; csharp: `McpServers`; go: `MCPServers`). Entrambi gli URL vengono normalizzati prima dell'associazione (schema e host convertiti in minuscolo, porte predefinite e barre finali rimosse), quindi differenze di maiuscole/minuscole nell'host, una porta predefinita o una barra finale non impediscono la corrispondenza; un percorso, un sottodominio o una porta non predefinita diversi invece sì. Se nessuna corrisponde, la connessione viene tentata senza autenticazione. Consulta [Aggiungi una credenziale](https://platform.claude.com/docs/it/managed-agents/vaults#add-a-credential) per i tipi di credenziale `static_bearer` e `mcp_oauth`. ### Gestisci gli errori di connessione e autenticazione La creazione della sessione non convalida la connettività MCP né le credenziali. Verifica invece l'host di ciascun server dichiarato rispetto alla configurazione di rete dell'ambiente: con un ambiente `limited`, la creazione della sessione fallisce con un errore 400 quando un host non è consentito, come descritto in [Fornisci l'autenticazione alla creazione della sessione](https://platform.claude.com/docs/it/managed-agents/mcp-connector#provide-authentication-at-session-creation). Se un server MCP non è raggiungibile o rifiuta la credenziale fornita, la sessione viene comunque avviata e l'interazione resta possibile. Viene emesso un evento [`session.error`](https://platform.claude.com/docs/it/managed-agents/reference#event-types) con il `mcp_server_name` (java, php: `mcpServerName`; csharp: `McpServerName`; go: `MCPServerName`) del server interessato e un `retry_status` (java, php: `retryStatus`; csharp, go: `RetryStatus`): | Tipo di errore | Significato | | --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `mcp_connection_failed_error` | Non è stato possibile raggiungere il server MCP (errore di rete, timeout o errore HTTP non legato all'autenticazione). | | `mcp_authentication_failed_error` | L'autenticazione con il server MCP è fallita: il server ha rifiutato la credenziale del vault associato, ha richiesto l'autenticazione quando non era configurata alcuna credenziale corrispondente, oppure il rinnovo di un token OAuth è fallito. | Puoi decidere se bloccare ulteriori interazioni in seguito a questo errore, attivare una rotazione delle credenziali o lasciare che la sessione continui senza gli strumenti del server interessato. La connessione viene ritentata alla successiva transizione da `session.status_idle` a `session.status_running`. ## Prossimi passi Controlla quando vengono eseguiti gli strumenti dell'agente e MCP. Invia eventi, ricevi risposte in streaming e interrompi o reindirizza la tua sessione durante l'esecuzione. Requisiti di trasporto per i server MCP remoti.