Conector MCP

Claude Managed Agents suporta a conexão de servidores Model Context Protocol (MCP) aos seus agentes. Isso fornece 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:

A criação do agente declara quais servidores MCP o agente conecta, por nome e URL.
A criação da sessão fornece autenticação para esses servidores referenciando um vault pré-registrado.

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

Todas as requisições da API Managed Agents requerem o cabeçalho beta managed-agents-2026-04-01. O SDK define o cabeçalho beta automaticamente.

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 único e uma url. Nenhum token de autenticação é fornecido nesta etapa.

O name que você atribui no array de servidores MCP é usado para referenciar as entradas mcp_toolset no array de ferramentas.

O conjunto de ferramentas MCP tem como padrão uma política de permissão always_ask, que requer aprovação do usuário antes de cada chamada de ferramenta. Consulte políticas de permissão para configurar esse comportamento.

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.

Se as credenciais de autorização fornecidas no vault forem inválidas, a criação da sessão será bem-sucedida e a interação ainda será possível. Um evento session.error é emitido descrevendo a falha de autenticação do MCP. Você pode decidir se bloqueia interações adicionais nesse erro, aciona uma atualização de credenciais ou permite que a sessão continue sem o MCP. As tentativas de autenticação ocorrerão na transição seguinte de session.status_idle para session.status_running. Consulte Fluxo de eventos da sessão para obter detalhes sobre como consumir session.error e outros eventos.

Tipos de servidores MCP suportados

Claude Managed Agents conecta-se a servidores MCP remotos que expõem um endpoint HTTP. O servidor deve suportar o transporte HTTP streamable do protocolo MCP.

Para mais informações sobre MCP e como construir servidores MCP, consulte a documentação do MCP.

agent_response=$(curl -sS --fail-with-body https://api.anthropic.com/v1/agents \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d @- <<'EOF'
{
  "name": "GitHub Assistant",
  "model": "claude-sonnet-4-6",
  "mcp_servers": [
    {
      "type": "url",
      "name": "github",
      "url": "https://api.githubcopilot.com/mcp/"
    }
  ],
  "tools": [
    {"type": "agent_toolset_20260401"},
    {"type": "mcp_toolset", "mcp_server_name": "github"}
  ]
}
EOF
)
agent_id=$(jq -r '.id' <<<"$agent_response")

session_response=$(curl -sS --fail-with-body https://api.anthropic.com/v1/sessions \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d @- <<EOF
{
  "agent": "$agent_id",
  "environment_id": "$environment_id",
  "vault_ids": ["$vault_id"]
}
EOF
)
session_id=$(jq -r '.id' <<<"$session_response")