--- title: Conector MCP url: https://platform.claude.com/docs/pt-BR/managed-agents/mcp-connector description: Conecte servidores MCP aos seus agentes para acessar ferramentas e fontes de dados externas. featureMetadata: topic: title: Managed Agents url: https://platform.claude.com/docs/en/managed-agents/overview status: beta betaHeader: managed-agents-2026-04-01 --- O Claude Managed Agents oferece suporte à conexão de servidores [Model Context Protocol (MCP)](https://modelcontextprotocol.io) 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](https://platform.claude.com/docs/pt-BR/managed-agents/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` (java, php: `mcpServers`; csharp: `McpServers`; go: `MCPServers`) ao criar um agente. Cada servidor precisa de um `type` (csharp, go: `Type`), um `name` (csharp, go: `Name`) exclusivo e uma `url` (csharp: `Url`; go: `URL`). Nenhum token de autenticação é fornecido nesta etapa. Cada servidor declarado também precisa de uma entrada `mcp_toolset` correspondente no array `tools` (csharp, go: `Tools`). O `mcp_server_name` (java, php: `mcpServerName`; csharp: `McpServerName`; go: `MCPServerName`) do toolset deve corresponder ao `name` (csharp, go: `Name`) do servidor. ```bash cURL 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 '{ "name": "GitHub Assistant", "model": "claude-opus-5-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"} ] }' ``` ```bash CLI ant apply github-assistant.md ``` ```markdown --- name: GitHub Assistant model: claude-opus-5-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 --- ``` ```python Python agent = client.beta.agents.create( name="GitHub Assistant", model="claude-opus-5-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"}, ], ) ``` ```typescript TypeScript const agent = await client.beta.agents.create({ name: "GitHub Assistant", model: "claude-opus-5-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" } ] }); ``` ```csharp C# var agent = await client.Beta.Agents.Create(new() { Name = "GitHub Assistant", Model = BetaManagedAgentsModel.ClaudeOpus5_5, McpServers = [ new() { Type = "url", Name = "github", Url = "https://api.githubcopilot.com/mcp/" }, ], Tools = [ new BetaManagedAgentsAgentToolset20260401Params { Type = "agent_toolset_20260401", }, new BetaManagedAgentsMcpToolsetParams { Type = "mcp_toolset", McpServerName = "github" }, ], }); ``` ```go Go agent, err := client.Beta.Agents.New(ctx, anthropic.BetaAgentNewParams{ Name: "GitHub Assistant", Model: anthropic.BetaManagedAgentsModelConfigParams{ ID: anthropic.BetaManagedAgentsModelClaudeOpus5_5, }, MCPServers: []anthropic.BetaManagedAgentsURLMCPServerParams{{ Type: anthropic.BetaManagedAgentsURLMCPServerParamsTypeURL, Name: "github", URL: "https://api.githubcopilot.com/mcp/", }}, Tools: []anthropic.BetaAgentNewParamsToolUnion{ { OfAgentToolset20260401: &anthropic.BetaManagedAgentsAgentToolset20260401Params{ Type: anthropic.BetaManagedAgentsAgentToolset20260401ParamsTypeAgentToolset20260401, }, }, { OfMCPToolset: &anthropic.BetaManagedAgentsMCPToolsetParams{ Type: anthropic.BetaManagedAgentsMCPToolsetParamsTypeMCPToolset, MCPServerName: "github", }, }, }, }) if err != nil { panic(err) } ``` ```java Java var agent = client.beta().agents().create( AgentCreateParams.builder() .name("GitHub Assistant") .model(BetaManagedAgentsModel.CLAUDE_OPUS_5_5) .addMcpServer( BetaManagedAgentsUrlMcpServerParams.builder() .type(BetaManagedAgentsUrlMcpServerParams.Type.URL) .name("github") .url("https://api.githubcopilot.com/mcp/") .build() ) .addTool( BetaManagedAgentsAgentToolset20260401Params.builder() .type(BetaManagedAgentsAgentToolset20260401Params.Type.AGENT_TOOLSET_20260401) .build() ) .addTool( BetaManagedAgentsMcpToolsetParams.builder() .type(BetaManagedAgentsMcpToolsetParams.Type.MCP_TOOLSET) .mcpServerName("github") .build() ) .build() ); ``` ```php PHP $agent = $client->beta->agents->create( name: 'GitHub Assistant', model: 'claude-opus-5-5', mcpServers: [ BetaManagedAgentsURLMCPServerParams::with( type: 'url', name: 'github', url: 'https://api.githubcopilot.com/mcp/', ), ], tools: [ BetaManagedAgentsAgentToolset20260401Params::with( type: 'agent_toolset_20260401', ), BetaManagedAgentsMCPToolsetParams::with( type: 'mcp_toolset', mcpServerName: 'github', ), ], ); ``` ```ruby Ruby agent = client.beta.agents.create( name: "GitHub Assistant", model: "claude-opus-5-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"} ] ) ``` O toolset MCP usa por padrão uma política de permissão `always_ask`, que exige a aprovação do usuário antes de cada chamada de ferramenta. Consulte [políticas de permissão](https://platform.claude.com/docs/pt-BR/managed-agents/permission-policies) para configurar esse comportamento. ### Referência do campo `mcp_servers` Cada entrada no array `mcp_servers` (java, php: `mcpServers`; csharp: `McpServers`; go: `MCPServers`) define uma conexão. | Campo | Descrição | | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `type` (csharp, go: `Type`) | Obrigatório. Deve ser `"url"`. | | `name` (csharp, go: `Name`) | Obrigatório. Um nome exclusivo para este servidor dentro do agente (1–255 caracteres). Usado como o `mcp_server_name` (java, php: `mcpServerName`; csharp: `McpServerName`; go: `MCPServerName`) no array `tools` (csharp, go: `Tools`) e exibido nos eventos de ferramentas MCP no [stream de eventos da sessão](https://platform.claude.com/docs/pt-BR/managed-agents/events-and-streaming). | | `url` (csharp: `Url`; go: `URL`) | Obrigatório. O endpoint do servidor MCP remoto (até 2.048 caracteres). Consulte [Tipos de servidores MCP compatíveis](https://platform.claude.com/docs/pt-BR/managed-agents/reference#supported-mcp-server-types) para os requisitos de transporte. | 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` (java, php: `mcpServers`; csharp: `McpServers`; go: `MCPServers`) deve ser referenciada por um `mcp_toolset` no array `tools` (csharp, go: `Tools`), e todo `mcp_toolset` deve referenciar um servidor declarado. A API rejeita definições de agente com servidores não referenciados ou toolsets órfãos. ## Configurar quais ferramentas MCP estão disponíveis A entrada `mcp_toolset` aceita um objeto `default_config` (java, php: `defaultConfig`; csharp, go: `DefaultConfig`) e um array `configs` (csharp, go: `Configs`), aplicados às ferramentas que o servidor MCP expõe. Cada entrada de `configs` (csharp, go: `Configs`) aceita apenas `name` (csharp, go: `Name`), `enabled` (csharp, go: `Enabled`) e `permission_policy` (java, php: `permissionPolicy`; csharp, go: `PermissionPolicy`). Diferentemente das entradas no toolset integrado do agente, as entradas de ferramentas MCP não recebem um campo `type` (csharp, go: `Type`), e as [configurações web](https://platform.claude.com/docs/pt-BR/managed-agents/tools-web-restrictions#settings) disponíveis em `web_search` e `web_fetch` não se aplicam às ferramentas MCP. O `name` (csharp, go: `Name`) em cada entrada de `configs` (csharp, go: `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: ```json { "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: ```json { "type": "mcp_toolset", "mcp_server_name": "github", "configs": [{ "name": "delete_repository", "enabled": false }] } ``` Consulte [configurando o toolset](https://platform.claude.com/docs/pt-BR/managed-agents/tools#configuring-the-toolset) para o padrão geral de `default_config` (java, php: `defaultConfig`; csharp, go: `DefaultConfig`) / `configs` (csharp, go: `Configs`), e [permissões do toolset MCP](https://platform.claude.com/docs/pt-BR/managed-agents/permission-policies#mcp-toolset-permissions) para definir `permission_policy` (java, php: `permissionPolicy`; csharp, go: `PermissionPolicy`) 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` (java: `vaultIds`; php: `vaultIDs`; csharp: `VaultIds`; go: `VaultIDs`) 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](https://platform.claude.com/docs/pt-BR/managed-agents/vaults) para saber como criar vaults e gerenciar credenciais. Com um [ambiente](https://platform.claude.com/docs/pt-BR/managed-agents/environments#networking) `limited`, a criação da sessão falha com um erro 400 quando o agente declara um servidor MCP cujo host não está em `allowed_hosts` (java, php: `allowedHosts`; csharp, go: `AllowedHosts`). Definir `allow_mcp_servers` (java: `allowMcpServers`; php: `allowMCPServers`; csharp: `AllowMcpServers`; go: `AllowMCPServers`) como `true` na configuração de rede do ambiente desativa essa verificação. ```bash cURL 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 '{ "agent": "'"$agent_id"'", "environment_id": "'"$environment_id"'", "vault_ids": ["'"$vault_id"'"] }' ``` ```bash CLI ant beta:sessions create \ --agent "$AGENT_ID" \ --environment-id "$ENVIRONMENT_ID" \ --vault-id "$VAULT_ID" ``` ```python Python session = client.beta.sessions.create( agent=agent.id, environment_id=environment.id, vault_ids=[vault.id], ) ``` ```typescript TypeScript const session = await client.beta.sessions.create({ agent: agent.id, environment_id: environment.id, vault_ids: [vault.id] }); ``` ```csharp C# var session = await client.Beta.Sessions.Create(new() { Agent = agent.ID, EnvironmentID = environment.ID, VaultIds = [vault.ID], }); ``` ```go Go session, err := client.Beta.Sessions.New(ctx, anthropic.BetaSessionNewParams{ Agent: anthropic.BetaSessionNewParamsAgentUnion{OfString: anthropic.String(agent.ID)}, EnvironmentID: environment.ID, VaultIDs: []string{vault.ID}, }) if err != nil { panic(err) } ``` ```java Java var session = client.beta().sessions().create( SessionCreateParams.builder() .agent(agent.id()) .environmentId(environment.id()) .addVaultId(vault.id()) .build() ); ``` ```php PHP $session = $client->beta->sessions->create( agent: $agent->id, environmentID: $environment->id, vaultIDs: [$vault->id], ); ``` ```ruby Ruby 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` (java: `mcpServerUrl`; php: `mcpServerURL`; csharp: `McpServerUrl`; go: `MCPServerURL`) se refira ao mesmo servidor que a `url` (csharp: `Url`; go: `URL`) declarada em `mcp_servers` (java, php: `mcpServers`; csharp: `McpServers`; go: `MCPServers`). Ambas as URLs são normalizadas antes da correspondência (esquema e host convertidos para minúsculas, portas padrão e barras finais removidas), de modo que diferenças de maiúsculas/minúsculas no 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 diferente impede. Se nenhuma corresponder, a conexão é tentada sem autenticação. Consulte [Adicionar uma credencial](https://platform.claude.com/docs/pt-BR/managed-agents/vaults#add-a-credential) 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. Ela verifica o host de cada servidor declarado em relação à configuração de rede do ambiente: com um ambiente `limited`, a criação da sessão falha com um erro 400 quando um host não é permitido, conforme descrito em [Fornecer autenticação na criação da sessão](https://platform.claude.com/docs/pt-BR/managed-agents/mcp-connector#provide-authentication-at-session-creation). Se um servidor MCP estiver inacessível ou rejeitar a credencial fornecida, a sessão ainda assim é iniciada e a interação continua possível. Um evento [`session.error`](https://platform.claude.com/docs/pt-BR/managed-agents/reference#event-types) é emitido com o `mcp_server_name` (java, php: `mcpServerName`; csharp: `McpServerName`; go: `MCPServerName`) do servidor afetado e um `retry_status` (java, php: `retryStatus`; csharp, go: `RetryStatus`): | Tipo de erro | Significado | | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `mcp_connection_failed_error` | Não foi possível alcançar o servidor MCP (erro de rede, tempo limite esgotado ou falha HTTP não relacionada à autenticação). | | `mcp_authentication_failed_error` | A autenticação com o servidor MCP falhou: o servidor rejeitou a credencial do vault anexado, exigiu autenticação quando nenhuma credencial correspondente estava configurada, ou a renovação de um token OAuth falhou. | 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 Controle quando as ferramentas do agente e do MCP são executadas. Envie eventos, receba respostas via streaming e interrompa ou redirecione sua sessão durante a execução. Requisitos de transporte para servidores MCP remotos.