--- title: Conector MCP url: https://platform.claude.com/docs/es/managed-agents/mcp-connector description: Conecta servidores MCP a tus agentes para acceder a herramientas y fuentes de datos externas. featureMetadata: topic: title: Managed Agents url: https://platform.claude.com/docs/en/managed-agents/overview status: beta betaHeader: managed-agents-2026-04-01 --- Claude Managed Agents admite la conexión de servidores [Model Context Protocol (MCP)](https://modelcontextprotocol.io) a tus agentes. Esto le da al agente acceso a herramientas externas, fuentes de datos y servicios a través de un protocolo estandarizado. La configuración de MCP se divide en dos pasos: 1. **La creación del agente** declara a qué servidores MCP se conecta el agente, por nombre y URL. 2. **La creación de la sesión** proporciona la autenticación para esos servidores haciendo referencia a un vault (bóveda) previamente registrado (consulta [Autenticar con vaults](https://platform.claude.com/docs/es/managed-agents/vaults)). Esta separación mantiene los secretos fuera de las definiciones de agentes reutilizables, a la vez que permite que cada sesión se autentique con sus propias credenciales. ## Declarar servidores MCP en el agente Especifica los servidores MCP en el array `mcp_servers` (java, php: `mcpServers`; csharp: `McpServers`; go: `MCPServers`) al crear un agente. Cada servidor necesita un `type` (csharp, go: `Type`), un `name` (csharp, go: `Name`) único y una `url` (csharp: `Url`; go: `URL`). En esta etapa no se proporcionan tokens de autenticación. Cada servidor declarado también necesita una entrada `mcp_toolset` correspondiente en el array `tools` (csharp, go: `Tools`). El `mcp_server_name` (java, php: `mcpServerName`; csharp: `McpServerName`; go: `MCPServerName`) del toolset debe coincidir con el `name` (csharp, go: `Name`) del 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"} ] ) ``` El toolset MCP usa de forma predeterminada una política de permisos `always_ask`, que requiere la aprobación del usuario antes de cada llamada a una herramienta. Consulta [políticas de permisos](https://platform.claude.com/docs/es/managed-agents/permission-policies) para configurar este comportamiento. ### Referencia del campo `mcp_servers` Cada entrada del array `mcp_servers` (java, php: `mcpServers`; csharp: `McpServers`; go: `MCPServers`) define una conexión. | Campo | Descripción | | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `type` (csharp, go: `Type`) | Obligatorio. Debe ser `"url"`. | | `name` (csharp, go: `Name`) | Obligatorio. Un nombre único para este servidor dentro del agente (de 1 a 255 caracteres). Se usa como el `mcp_server_name` (java, php: `mcpServerName`; csharp: `McpServerName`; go: `MCPServerName`) en el array `tools` (csharp, go: `Tools`) y aparece en los eventos de herramientas MCP del [flujo de eventos de la sesión](https://platform.claude.com/docs/es/managed-agents/events-and-streaming). | | `url` (csharp: `Url`; go: `URL`) | Obligatorio. El endpoint del servidor MCP remoto (hasta 2,048 caracteres). Consulta [Tipos de servidores MCP compatibles](https://platform.claude.com/docs/es/managed-agents/reference#supported-mcp-server-types) para conocer los requisitos de transporte. | Restricciones: * Un agente puede declarar hasta 20 servidores MCP. Los nombres de los servidores deben ser únicos dentro del array. * Cada entrada de `mcp_servers` (java, php: `mcpServers`; csharp: `McpServers`; go: `MCPServers`) debe estar referenciada por un `mcp_toolset` en el array `tools` (csharp, go: `Tools`), y cada `mcp_toolset` debe hacer referencia a un servidor declarado. La API rechaza las definiciones de agentes con servidores no referenciados o toolsets huérfanos. ## Configurar qué herramientas MCP están disponibles La entrada `mcp_toolset` admite un objeto `default_config` (java, php: `defaultConfig`; csharp, go: `DefaultConfig`) y un array `configs` (csharp, go: `Configs`), que se aplican a las herramientas que expone el servidor MCP. Cada entrada de `configs` (csharp, go: `Configs`) acepta solo `name` (csharp, go: `Name`), `enabled` (csharp, go: `Enabled`) y `permission_policy` (java, php: `permissionPolicy`; csharp, go: `PermissionPolicy`). A diferencia de las entradas del toolset integrado del agente, las entradas de herramientas MCP no aceptan un campo `type` (csharp, go: `Type`), y la [configuración web](https://platform.claude.com/docs/es/managed-agents/tools-web-restrictions#settings) disponible en `web_search` y `web_fetch` no se aplica a las herramientas MCP. El `name` (csharp, go: `Name`) de cada entrada de `configs` (csharp, go: `Configs`) es el nombre simple de la herramienta tal como lo informa el servidor. De forma predeterminada, todas las herramientas expuestas por el servidor MCP están habilitadas. Para habilitar solo herramientas específicas, establece `default_config.enabled` en `false` y habilita explícitamente las herramientas que quieras: ```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 } ] } ``` Este patrón es útil cuando un servidor expone muchas herramientas pero el agente solo necesita unas pocas, o cuando quieres que las herramientas añadidas por el operador del servidor permanezcan desactivadas hasta que las revises. Para deshabilitar herramientas específicas manteniendo el resto habilitadas, omite `default_config` y establece `enabled: false` en las entradas individuales: ```json { "type": "mcp_toolset", "mcp_server_name": "github", "configs": [{ "name": "delete_repository", "enabled": false }] } ``` Consulta [configurar el toolset](https://platform.claude.com/docs/es/managed-agents/tools#configuring-the-toolset) para conocer el patrón general de `default_config` (java, php: `defaultConfig`; csharp, go: `DefaultConfig`) / `configs` (csharp, go: `Configs`), y [permisos del toolset MCP](https://platform.claude.com/docs/es/managed-agents/permission-policies#mcp-toolset-permissions) para establecer `permission_policy` (java, php: `permissionPolicy`; csharp, go: `PermissionPolicy`) en herramientas MCP y gestionar las solicitudes de confirmación. ### Manejo de la salida de herramientas MCP Cuando la salida de una herramienta MCP supera los 100,000 caracteres (aproximadamente 25,000 tokens), se escribe automáticamente en un archivo en el sandbox. El modelo recibe una vista previa truncada con la ruta del archivo y puede leer el contenido completo desde allí. ## Proporcionar autenticación al crear la sesión Al iniciar una sesión, pasa `vault_ids` (java: `vaultIds`; php: `vaultIDs`; csharp: `VaultIds`; go: `VaultIDs`) para proporcionar credenciales para tus servidores MCP. Los vaults son colecciones de credenciales que registras una vez y a las que haces referencia por ID. Consulta [Autenticar con vaults](https://platform.claude.com/docs/es/managed-agents/vaults) para saber cómo crear vaults y gestionar credenciales. Con un [entorno](https://platform.claude.com/docs/es/managed-agents/environments#networking) `limited`, la creación de la sesión falla con un error 400 cuando el agente declara un servidor MCP cuyo host no está en `allowed_hosts` (java, php: `allowedHosts`; csharp, go: `AllowedHosts`). Establecer `allow_mcp_servers` (java: `allowMcpServers`; php: `allowMCPServers`; csharp: `AllowMcpServers`; go: `AllowMCPServers`) en `true` en la configuración de red del entorno desactiva esta comprobación. ```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] ) ``` Las credenciales se emparejan por URL, por lo que el vault debe contener una credencial cuyo `mcp_server_url` (java: `mcpServerUrl`; php: `mcpServerURL`; csharp: `McpServerUrl`; go: `MCPServerURL`) haga referencia al mismo servidor que la `url` (csharp: `Url`; go: `URL`) declarada en `mcp_servers` (java, php: `mcpServers`; csharp: `McpServers`; go: `MCPServers`). Ambas URL se normalizan antes de emparejarlas (el esquema y el host se convierten a minúsculas, y se eliminan los puertos predeterminados y las barras finales), por lo que las diferencias en mayúsculas y minúsculas del host, un puerto predeterminado o una barra final no impiden la coincidencia; una ruta, un subdominio o un puerto no predeterminado diferentes sí la impiden. Si ninguna coincide, se intenta la conexión sin autenticación. Consulta [Agregar una credencial](https://platform.claude.com/docs/es/managed-agents/vaults#add-a-credential) para conocer los tipos de credenciales `static_bearer` y `mcp_oauth`. ### Manejar fallos de conexión y autenticación La creación de la sesión no valida la conectividad ni las credenciales de MCP. Sí comprueba el host de cada servidor declarado con la configuración de red del entorno: con un entorno `limited`, la creación de la sesión falla con un error 400 cuando un host no está permitido, como se describe en [Proporcionar autenticación al crear la sesión](https://platform.claude.com/docs/es/managed-agents/mcp-connector#provide-authentication-at-session-creation). Si un servidor MCP no es accesible o rechaza la credencial proporcionada, la sesión se inicia de todos modos y la interacción sigue siendo posible. Se emite un evento [`session.error`](https://platform.claude.com/docs/es/managed-agents/reference#event-types) con el `mcp_server_name` (java, php: `mcpServerName`; csharp: `McpServerName`; go: `MCPServerName`) del servidor afectado y un `retry_status` (java, php: `retryStatus`; csharp, go: `RetryStatus`): | Tipo de error | Significado | | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `mcp_connection_failed_error` | No se pudo acceder al servidor MCP (error de red, tiempo de espera agotado o fallo HTTP no relacionado con la autenticación). | | `mcp_authentication_failed_error` | La autenticación con el servidor MCP falló: el servidor rechazó la credencial del vault adjunto, requirió autenticación cuando no había ninguna credencial coincidente configurada, o falló la renovación de un token OAuth. | Puedes decidir si bloquear la interacción posterior ante este error, activar una rotación de credenciales o dejar que la sesión continúe sin las herramientas del servidor afectado. La conexión se reintenta en la siguiente transición de `session.status_idle` a `session.status_running`. ## Próximos pasos Controla cuándo se ejecutan las herramientas del agente y de MCP. Envía eventos, recibe respuestas en streaming e interrumpe o redirige tu sesión en plena ejecución. Requisitos de transporte para servidores MCP remotos.