Compartir comentarios
Las respuestas se generan en base a la documentación.

Modo MCP

Tabla de contenidos

Cuando ejecutas Docker Agent en modo MCP (Model Context Protocol), tus agentes aparecen como herramientas en Claude Desktop y otros clientes MCP. En lugar de cambiar a un terminal para ejecutar tu agente de seguridad, le pides a Claude que lo use y Claude lo llama por ti.

Esta guía cubre la configuración para Claude Desktop y Claude Code. Si en su lugar deseas agentes incrustados en tu editor, consulta la integración ACP.

Cómo funciona

Configuras Claude Desktop (u otro cliente MCP) para conectarse a Docker Agent. Tus agentes aparecen en la lista de herramientas de Claude. Cuando le pides a Claude que use uno, llama a ese agente a través del protocolo MCP.

Supongamos que tienes configurado un agente de seguridad. Pídele a Claude Desktop "Utiliza el agente de seguridad para auditar este código de autenticación" y Claude lo llamará. El agente se ejecuta con sus herramientas configuradas (sistema de archivos, shell o lo que le hayas asignado) y luego devuelve los resultados a Claude.

Si tu configuración tiene múltiples agentes, cada uno se convierte en una herramienta independiente. Una configuración con agentes root, designer y engineer le ofrece a Claude tres herramientas para elegir. Claude podría llamar al ingeniero directamente o utilizar el coordinador root; depende de las descripciones de tus agentes y de lo que solicites.

Puerta de enlace MCP (MCP Gateway)

Docker proporciona una MCP Gateway que da acceso a los agentes a un catálogo de servidores MCP preconfigurados. En lugar de configurar servidores MCP individuales, los agentes pueden usar la puerta de enlace para acceder a herramientas como búsqueda web, consultas de bases de datos y más.

Configura el conjunto de herramientas (toolsets) de MCP con la referencia de la puerta de enlace:

agents:
  root:
    toolsets:
      - type: mcp
        ref: docker:duckduckgo # Utiliza la MCP Gateway de Docker

El prefijo docker: le indica a Docker Agent que use la MCP Gateway para este servidor. Consulta el Catálogo MCP para ver los servidores disponibles y la documentación de la MCP Gateway para conocer las opciones de configuración.

También puedes usar el MCP Toolkit para explorar y gestionar servidores MCP de forma interactiva.

Requisitos previos

Antes de configurar la integración MCP, necesitas:

  • Docker Agent instalado - Consulta la guía de instalación
  • Configuración del agente - Un archivo YAML que define tu agente. Consulta el tutorial o las configuraciones de ejemplo
  • Cliente MCP - Claude Desktop, Claude Code u otra aplicación compatible con MCP
  • Claves de API - Variables de entorno para cualquier proveedor de modelos que utilicen tus agentes (ANTHROPIC_API_KEY, OPENAI_API_KEY, etc.)

Configuración del cliente MCP

Tu cliente MCP necesita saber cómo iniciar Docker Agent y comunicarse con él. Esto normalmente implica añadir Docker Agent como un servidor MCP en la configuración de tu cliente.

Claude Desktop

Añade Docker Agent a tu archivo de configuración de MCP en Claude Desktop:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json

Ejemplo de configuración:

{
  "mcpServers": {
    "myagent": {
      "command": "docker",
      "args": [
        "agent",
        "serve",
        "mcp",
        "/path/to/agent.yml",
        "--working-dir",
        "/Users/yourname/projects"
      ],
      "env": {
        "ANTHROPIC_API_KEY": "your_anthropic_key_here",
        "OPENAI_API_KEY": "your_openai_key_here"
      }
    }
  }
}

Desglose de la configuración:

  • command: Ruta completa a tu binario docker (usa which docker para encontrarlo), o la ruta a docker-agent si no estás utilizando el plugin de CLI de Docker
  • args: Argumentos del comando MCP:
    • mcp: El subcomando para ejecutar docker agent en modo MCP
    • dockereng/myagent: Tu configuración de agente (ruta de archivo local o referencia a OCI)
    • --working-dir: Directorio de trabajo opcional para la ejecución del agente
  • env: Variables de entorno que tus agentes necesitan:
    • Claves de API de proveedores de modelos (ANTHROPIC_API_KEY, OPENAI_API_KEY, etc.)
    • Cualquier otra variable de entorno a la que tus agentes hagan referencia

Después de actualizar la configuración, reinicia Claude Desktop. Tus agentes aparecerán como herramientas disponibles.

Claude Code

Añade Docker Agent como un servidor MCP usando el comando claude mcp add:

$ claude mcp add --transport stdio myagent \
  --env OPENAI_API_KEY=$OPENAI_API_KEY \
  --env ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
  -- docker agent serve mcp /path/to/agent.yml --working-dir $(pwd)

Desglose del comando:

  • claude mcp add: Comando de Claude Code para registrar un servidor MCP
  • --transport stdio: Utiliza transporte stdio (estándar para servidores MCP locales)
  • myagent: Nombre para este servidor MCP en Claude Code
  • --env: Pasa variables de entorno (repite para cada variable)
  • --: Separa las opciones de Claude Code del comando del servidor MCP
  • docker agent serve mcp /path/to/agent.yml: El comando MCP de Docker Agent con la ruta a tu configuración de agente
  • --working-dir $(pwd): Establece el directorio de trabajo para la ejecución del agente

Después de añadir el servidor, tus agentes estarán disponibles como herramientas en las sesiones de Claude Code.

Otros clientes MCP

Para otros clientes compatibles con MCP, necesitas hacer lo siguiente:

  1. Iniciar Docker Agent con docker agent serve mcp /path/to/agent.yml --working-dir /ruta/del/proyecto
  2. Configurar el cliente para comunicarse con Docker Agent a través de stdio
  3. Pasar las variables de entorno requeridas (claves de API, etc.)

Consulta la documentación de tu cliente MCP para conocer los pasos de configuración específicos.

Referencias de agentes

Puedes especificar la configuración de tu agente como una ruta de archivo local o una referencia a un registro OCI:

# Ruta de archivo local
$ docker agent serve mcp ./agent.yml

# Referencia a un registro OCI
$ docker agent serve mcp agentcatalog/pirate
$ docker agent serve mcp dockereng/myagent:v1.0.0

Utiliza la misma sintaxis en las configuraciones del cliente MCP:

{
  "mcpServers": {
    "myagent": {
      "command": "docker",
      "args": ["agent", "serve", "mcp", "agentcatalog/pirate"]
    }
  }
}

Las referencias de registro permiten que tu equipo use la misma configuración de agente sin tener que gestionar archivos locales. Consulta Compartir agentes para más detalles.

Diseño de agentes para MCP

Los clientes MCP ven a cada uno de tus agentes como una herramienta independiente y pueden llamar a cualquiera de ellos directamente. Esto cambia la forma en que debes pensar sobre el diseño de agentes en comparación con ejecutarlos con docker agent run.

Escribe buenas descripciones

El campo description le indica al cliente MCP qué hace el agente. Así es como el cliente decide cuándo llamarlo. "Analiza el código en busca de vulnerabilidades de seguridad y problemas de cumplimiento" es específico. "Un agente de seguridad útil" no explica lo que hace realmente.

agents:
  security_auditor:
    description: Analiza el código en busca de vulnerabilidades de seguridad y problemas de cumplimiento
    # No utilizar: "Un agente de seguridad útil"

Los clientes MCP llaman a los agentes directamente

El cliente MCP puede llamar a cualquiera de tus agentes, no solo al root. Si tienes agentes root, designer y engineer, el cliente podría llamar al ingeniero directamente en lugar de pasar por el root. Diseña cada agente para que funcione por su cuenta:

agents:
  engineer:
    description: Implementa características y escribe código de producción
    instruction: |
      Implementas código basándote en los requisitos proporcionados.
      Puedes trabajar de forma independiente sin un coordinador.
    toolsets:
      - type: filesystem
      - type: shell

Si un agente necesita de otros para funcionar correctamente, indícalo en la descripción: "Coordina los agentes de diseño e ingeniería para implementar características completas."

Prueba cada agente por separado

Los clientes MCP llaman a los agentes individualmente, por lo que debes probarlos de esa manera:

$ docker agent run agent.yml --agent engineer

Asegúrate de que el agente funcione sin pasar primero por el root. Comprueba que tiene las herramientas adecuadas y que sus instrucciones tienen sentido cuando se le llama directamente.

Probar tu configuración

Verifica que tu integración MCP funcione:

  1. Reinicia tu cliente MCP después de realizar cambios de configuración
  2. Comprueba que los agentes aparecen como herramientas disponibles
  3. Invoca a un agente con un prompt de prueba sencillo
  4. Verifica que el agente pueda acceder a sus herramientas configuradas (sistema de archivos, shell, etc.)

Si los agentes no aparecen o no se ejecutan, verifica lo siguiente:

  • El comando docker agent está disponible y es ejecutable
  • El archivo de configuración del agente existe y es válido
  • Todas las claves de API requeridas están configuradas en las variables de entorno
  • La ruta del directorio de trabajo existe y tiene los permisos adecuados
  • Los registros del cliente MCP en busca de errores de conexión o de ejecución

Flujos de trabajo comunes

Llamar a agentes especialistas

Tienes un agente de seguridad que conoce tus reglas de cumplimiento y vulnerabilidades comunes. En Claude Desktop, pega un poco de código de autenticación y solicita "Utiliza el agente de seguridad para revisar esto". El agente comprueba el código y reporta lo que encuentra. Permaneces en la interfaz de Claude todo el tiempo.

Trabajar con equipos de agentes

Tu configuración tiene un coordinador que delega en agentes de diseño (designer) e ingeniería (engineer). Pregúntale a Claude Code "Usa el coordinador para implementar un formulario de inicio de sesión" y el coordinador pasará el trabajo de UI al diseñador y el código al ingeniero. Obtienes una implementación completa sin ejecutar docker agent run por ti mismo.

Ejecutar herramientas específicas de un dominio

Creaste un agente de infraestructura con scripts de despliegue personalizados y consultas de monitoreo. Pídele a cualquier cliente MCP "Utiliza el agente de infraestructura para verificar el estado de producción" y ejecutará tus herramientas y devolverá los resultados. Tus conocimientos de despliegue ahora están disponibles dondequiera que uses clientes MCP.

Compartir agentes

Tu equipo mantiene los agentes en un registro OCI. Todos añaden agentcatalog/security-expert a la configuración de su cliente MCP. Cuando actualizas el agente, obtienen la nueva versión en su próximo reinicio. Sin necesidad de pasarse archivos YAML.

¿Qué sigue?