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. Creación del agente: declara a qué servidores MCP se conecta el agente, por nombre y URL.
2. Creación de la sesión: proporciona la autenticación para esos servidores haciendo referencia a un vault registrado previamente (consulta Autenticar con vaults).

Esta separación mantiene los secretos fuera de las definiciones de agentes reutilizables, mientras 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. En esta etapa no se proporcionan tokens de autenticación.

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 \
  --name "GitHub Assistant" \
  --model '{id: claude-opus-5}' \
  --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)



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 definiciones de agentes con servidores sin referenciar o toolsets sin servidor correspondiente.



Configurar qué herramientas MCP están disponibles

La entrada mcp_toolset admite la misma estructura de default_config y configs que el toolset integrado del agente, aplicada a las herramientas que expone el servidor 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 quieras:

{
  "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 manteniendo el resto habilitadas, omite default_config y establece enabled: false en las entradas individuales:

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

Consulta configurar el toolset para el patrón general de default_config / configs, y permisos del toolset de 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 (alrededor de 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 para 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 se refiera al mismo servidor que la url declarada en mcp_servers. Ambas URLs se normalizan antes del emparejamiento (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 una coincidencia; una ruta, un subdominio o un puerto no predeterminado diferentes sí lo hacen. Si ninguna coincide, la conexión se intenta sin autenticación. Consulta Agregar una credencial para 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 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 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 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