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 autenticação para esses servidores referenciando um vault pré-registrado (consulte Autenticar com vaults).

Essa separação mantém 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 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.
• Cada entrada em mcp_servers deve ser referenciada por um mcp_toolset no array tools, e cada mcp_toolset deve referenciar um servidor declarado. A API rejeita definições de agente com servidores não referenciados ou toolsets pendentes.



Configurar quais ferramentas MCP estão disponíveis

A entrada mcp_toolset suporta um objeto default_config e um array configs, aplicados às ferramentas que o servidor MCP expõe. Cada entrada em 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 a ferramentas MCP. O name em cada entrada de configs é o nome simples da ferramenta conforme reportado 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 que você deseja:

{
  "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ê quer que 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 em 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 é automaticamente gravada 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 dele.



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, então 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 convertidos para minúsculas, portas padrão e barras finais removidas), então 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 MCP nem as credenciais. 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 deseja bloquear interações adicionais com base nesse erro, acionar uma rotação de credenciais ou deixar 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