Connettore MCP

Claude Managed Agents supporta la connessione di server Model Context Protocol (MCP) ai tuoi agenti. Questo fornisce 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, tramite nome e URL.
2. La creazione della sessione fornisce l'autenticazione per quei server facendo riferimento a un vault pre-registrato.

Questa separazione mantiene i segreti fuori dalle definizioni riutilizzabili degli agenti, consentendo al contempo a ogni sessione di autenticarsi con le proprie credenziali.



Dichiarare i server MCP sull'agente

Specifica i server MCP nell'array mcp_servers quando crei un agente. Ogni server necessita di un type, un name univoco e un url. In questa fase non vengono forniti token di autenticazione.

Ogni server dichiarato necessita anche di una voce mcp_toolset corrispondente nell'array tools. Il mcp_server_name del toolset deve corrispondere al name del server.

AGENT_ID=$(ant beta:agents create \
  --name "GitHub Assistant" \
  --model claude-opus-4-8 \
  --mcp-server '{type: url, name: github, url: "https://api.githubcopilot.com/mcp/"}' \
  --tool '{type: agent_toolset_20260401}' \
  --tool '{type: mcp_toolset, mcp_server_name: github}' \
  --transform id --raw-output)



Riferimento del campo mcp_servers

Ogni voce nell'array mcp_servers definisce una connessione.

Vincoli:

• Un agente può dichiarare fino a 20 server MCP. I nomi dei server devono essere univoci all'interno dell'array.
• Ogni voce mcp_servers deve essere referenziata da un mcp_toolset nell'array 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.



Configurare quali strumenti MCP sono disponibili

La voce mcp_toolset supporta la stessa struttura default_config e configs del toolset integrato dell'agente, applicata agli strumenti esposti dal server MCP. Il name in ogni voce configs è il nome semplice dello strumento 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 desiderati:

{
  "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 pattern è utile quando un server espone molti strumenti ma l'agente ne necessita solo alcuni, o quando vuoi che gli strumenti aggiunti dall'operatore del server rimangano disabilitati finché non li esamini.

Per disabilitare strumenti specifici mantenendo abilitati gli altri, ometti default_config e imposta enabled: false sulle singole voci:

{
  "type": "mcp_toolset",
  "mcp_server_name": "github",
  "configs": [{ "name": "delete_repository", "enabled": false }]
}

Consulta configurazione del toolset per il pattern generale default_config / configs, e autorizzazioni del toolset MCP per impostare permission_policy 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 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ì.



Fornire l'autenticazione alla creazione della sessione

Quando avvii una sessione, passa vault_ids per fornire le credenziali per i tuoi server MCP. I vault sono raccolte di credenziali che registri una volta e a cui fai riferimento tramite ID. Consulta Autenticazione con i vault per scoprire come creare vault e gestire le credenziali.

session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    vault_ids=[vault.id],
)

Le credenziali vengono abbinate tramite URL, quindi il vault deve contenere una credenziale il cui mcp_server_url corrisponda esattamente all'url dichiarato in mcp_servers. Se nessuna corrisponde, la connessione viene tentata senza autenticazione. Consulta Aggiungere una credenziale per i tipi di credenziali static_bearer e mcp_oauth.



Gestire gli errori di connessione e autenticazione

La creazione della sessione non convalida la connettività MCP o le credenziali. Se un server MCP non è raggiungibile o rifiuta la credenziale fornita, la sessione viene comunque avviata e l'interazione rimane possibile. Viene emesso un evento session.error con il mcp_server_name del server interessato e un retry_status:

Puoi decidere se bloccare ulteriori interazioni in caso di 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.



Passaggi successivi