Conector MCP

Claude Managed Agents admite la conexión de servidores Model Context Protocol (MCP) 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) registrado previamente (consulta Autenticar con vaults).

Esta separación mantiene los secretos fuera de las definiciones de agentes reutilizables, al tiempo que permite que cada sesión se autentique con sus propias credenciales.



Declarar servidores MCP en el agente

Especifica los servidores MCP en el arreglo mcp_servers al crear un agente. Cada servidor necesita un type, un name único y una url. No se proporcionan tokens de autenticación en esta etapa.

Cada servidor declarado también necesita una entrada mcp_toolset correspondiente en el arreglo tools. El mcp_server_name del toolset debe coincidir con el name del 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



Referencia del campo mcp_servers

Cada entrada en el arreglo mcp_servers define una conexión.

Restricciones:

• Un agente puede declarar hasta 20 servidores MCP. Los nombres de los servidores deben ser únicos dentro del arreglo.
• Cada entrada de mcp_servers debe ser referenciada por un mcp_toolset en el arreglo 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 sin correspondencia.



Configurar qué herramientas MCP están disponibles

La entrada mcp_toolset admite un objeto default_config y un arreglo configs, que se aplican a las herramientas que expone el servidor MCP. Cada entrada de configs acepta únicamente name, enabled y permission_policy. A diferencia de las entradas en el toolset integrado del agente, las entradas de herramientas MCP no aceptan un campo type, y la configuración web disponible en web_search y web_fetch no se aplica a las herramientas MCP. El name en cada entrada de configs es el nombre simple de la herramienta tal como lo reporta 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 deseas:

{
  "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 agregadas por el operador del servidor permanezcan desactivadas hasta que las revises.

Para deshabilitar herramientas específicas mientras mantienes el resto habilitado, omite default_config y establece enabled: false en entradas individuales:

{
  "type": "mcp_toolset",
  "mcp_server_name": "github",
  "configs": [{ "name": "delete_repository", "enabled": false }]
}

Consulta configurar el toolset para conocer el patrón general de default_config / configs, y permisos del toolset MCP para establecer permission_policy en herramientas MCP y manejar 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 para proporcionar credenciales a tus servidores MCP. Los vaults son colecciones de credenciales que registras una vez y referencias por ID. Consulta Autenticar con vaults para saber cómo crear vaults y administrar credenciales.

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 haga referencia al mismo servidor que la url declarada en mcp_servers. Ambas URL se normalizan antes de compararse (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 las mayúsculas del host, un puerto predeterminado o una barra final no impiden la coincidencia; una ruta diferente, un subdominio distinto o un puerto no predeterminado sí lo hacen. Si ninguna coincide, la conexión se intenta sin autenticación. Consulta Agregar una credencial 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. Si un servidor MCP no está disponible 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 con el mcp_server_name del servidor afectado y un retry_status:

Puedes decidir si bloquear la interacción posterior ante este error, activar una rotación de credenciales o permitir 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