Connettore MCP

Claude Managed Agents supporta la connessione di server Model Context Protocol (MCP) 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).

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

Configura 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 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 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:

{
  "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:

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

Consulta configurazione del toolset per lo schema 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ì.

Fornisci 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 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 per URL, quindi il vault deve contenere una credenziale il cui mcp_server_url si riferisca allo stesso server dell'url dichiarato in mcp_servers. Entrambi gli URL vengono normalizzati prima dell'abbinamento (schema e host in minuscolo, porte predefinite e barre finali rimosse), quindi differenze nelle maiuscole dell'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 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. Se un server MCP non è raggiungibile o rifiuta la credenziale fornita, la sessione si avvia comunque e l'interazione resta 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 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