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 (vedi Autenticare con i vault).

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 richiede un type, un name univoco e un url. In questa fase non vengono forniti token di autenticazione.

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

AGENT_ID=$(ant beta:agents create --transform id --raw-output < github-assistant.agent.yaml)

name: GitHub Assistant
model:
  id: claude-opus-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



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 in 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 un oggetto default_config e un array configs, applicati agli strumenti esposti dal server MCP. Ogni voce in configs accetta solo name, enabled e permission_policy. A differenza delle voci nel toolset integrato dell'agente, le voci degli strumenti MCP non accettano un campo type, e le impostazioni web disponibili su web_search e web_fetch non si applicano agli strumenti MCP. Il name in ogni voce di 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 che desideri:

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

Vedi configurare il 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 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ì.



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. Vedi Autenticare con i vault per sapere 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 fa riferimento allo stesso server dell'url dichiarato in mcp_servers. Entrambi gli URL vengono normalizzati prima dell'abbinamento (schema e host convertiti in minuscolo, porte predefinite e barre finali rimosse), quindi differenze nelle maiuscole/minuscole dell'host, una porta predefinita o una barra finale non impediscono l'abbinamento; un percorso, un sottodominio o una porta non predefinita diversi invece sì. Se nessuna corrisponde, la connessione viene tentata senza autenticazione. Vedi Aggiungere una credenziale per i tipi di credenziale static_bearer e mcp_oauth.



Gestire gli errori di connessione e autenticazione

La creazione della sessione non convalida la connettività MCP né 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