Conector MCP

O Claude Managed Agents oferece suporte à conexão de servidores "Model Context Protocol", ou 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.

Essa separação mantém segredos fora das definições reutilizáveis de agentes, permitindo 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 \
  --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)



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 agentes com servidores não referenciados ou toolsets pendentes.



Configurar quais ferramentas MCP estão disponíveis

A entrada mcp_toolset suporta a mesma estrutura de default_config e configs que o toolset de agente integrado, aplicada às ferramentas que o servidor MCP expõe. 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 o restante habilitado, 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 de saída de ferramentas MCP

Quando a saída de uma ferramenta MCP excede 100.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 corresponda exatamente à url declarada em mcp_servers. 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