Conector MCP

O Claude Managed Agents oferece suporte à conexão de servidores Model Context Protocol (MCP) aos seus agentes. Isso dá ao agente acesso a ferramentas externas, fontes de dados e serviços por meio de um protocolo padronizado.

A configuração do MCP é dividida em duas etapas:

1. A criação do agente declara a quais servidores MCP o agente se conecta, por nome e URL.
2. A criação da sessão fornece a autenticação para esses servidores referenciando um vault (cofre) pré-registrado (consulte Autenticar com vaults).

Essa separação mantém os segredos fora das definições reutilizáveis de agentes, ao mesmo tempo que permite que cada sessão se autentique com suas próprias credenciais.

Declarar servidores MCP no agente

Especifique os servidores MCP no array mcp_servers ao criar um agente. Cada servidor precisa de um type, um name exclusivo e uma url. Nenhum token de autenticação é fornecido nesta etapa.

Cada servidor declarado também precisa de uma entrada mcp_toolset correspondente no array tools. O mcp_server_name do toolset deve corresponder ao name do servidor.

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

Referência do campo mcp_servers

Cada entrada no array mcp_servers define uma conexão.

Restrições:

• Um agente pode declarar até 20 servidores MCP. Os nomes dos servidores devem ser exclusivos dentro do array.
• Toda entrada de mcp_servers deve ser referenciada por um mcp_toolset no array tools, e todo mcp_toolset deve referenciar um servidor declarado. A API rejeita definições de agentes com servidores não referenciados ou toolsets sem servidor correspondente.

Configurar quais ferramentas MCP estão disponíveis

A entrada mcp_toolset oferece suporte a um objeto default_config e a um array configs, aplicados às ferramentas que o servidor MCP expõe. Cada entrada de configs aceita apenas name, enabled e permission_policy. Diferentemente das entradas no toolset integrado do agente, as entradas de ferramentas MCP não recebem um campo type, e as configurações web disponíveis em web_search e web_fetch não se aplicam às ferramentas MCP. O name em cada entrada de configs é o nome simples da ferramenta, conforme informado pelo servidor.

Por padrão, todas as ferramentas expostas pelo servidor MCP estão habilitadas. Para habilitar apenas ferramentas específicas, defina default_config.enabled como false e habilite explicitamente as ferramentas desejadas:

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

Esse padrão é útil quando um servidor expõe muitas ferramentas, mas o agente precisa apenas de algumas, ou quando você deseja que as ferramentas adicionadas pelo operador do servidor permaneçam desativadas até que você as revise.

Para desabilitar ferramentas específicas mantendo as demais habilitadas, omita default_config e defina enabled: false nas entradas individuais:

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

Consulte configurando o toolset para o padrão geral de default_config / configs, e permissões do toolset MCP para definir permission_policy em ferramentas MCP e lidar com solicitações de confirmação.

Tratamento da saída de ferramentas MCP

Quando a saída de uma ferramenta MCP excede 100.000 caracteres (cerca de 25.000 tokens), ela é gravada automaticamente em um arquivo no sandbox. O modelo recebe uma prévia truncada com o caminho do arquivo e pode ler o conteúdo completo a partir dali.

Fornecer autenticação na criação da sessão

Ao iniciar uma sessão, passe vault_ids para fornecer credenciais para seus servidores MCP. Vaults são coleções de credenciais que você registra uma vez e referencia por ID. Consulte Autenticar com vaults para saber como criar vaults e gerenciar credenciais.

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

As credenciais são correspondidas por URL, portanto o vault deve conter uma credencial cujo mcp_server_url se refira ao mesmo servidor que a url declarada em mcp_servers. Ambas as URLs são normalizadas antes da correspondência (esquema e host em minúsculas, portas padrão e barras finais removidas), de modo que diferenças na capitalização do host, uma porta padrão ou uma barra final não impedem a correspondência; um caminho, subdomínio ou porta não padrão diferentes impedem. Se nenhuma corresponder, a conexão é tentada sem autenticação. Consulte Adicionar uma credencial para os tipos de credencial static_bearer e mcp_oauth.

Lidar com falhas de conexão e autenticação

A criação da sessão não valida a conectividade nem as credenciais do MCP. Se um servidor MCP estiver inacessível ou rejeitar a credencial fornecida, a sessão ainda é iniciada e a interação continua possível. Um evento session.error é emitido com o mcp_server_name do servidor afetado e um retry_status:

Você pode decidir se bloqueia interações adicionais diante desse erro, aciona uma rotação de credenciais ou deixa a sessão continuar sem as ferramentas do servidor afetado. A conexão é tentada novamente na próxima transição de session.status_idle para session.status_running.

Próximos passos