# Modo MCP


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](/ai/docker-agent/integrations/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](/ai/mcp-catalog-and-toolkit/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:

```yaml
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](/ai/mcp-catalog-and-toolkit/catalog/) para ver los servidores disponibles y la
[documentación de la MCP Gateway](/ai/mcp-catalog-and-toolkit/mcp-gateway/) para
conocer las opciones de configuración.

También puedes usar el [MCP Toolkit](/ai/mcp-catalog-and-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](/ai/integrations/#instalacion)
- **Configuración del agente** - Un archivo YAML que define tu agente. Consulta el
  [tutorial](/ai/docker-agent/tutorial/) o las [configuraciones de
  ejemplo](https://github.com/docker/docker-agent/tree/main/examples)
- **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:

```json
{
  "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`:

```console
$ 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:

```console
# 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:

```json
{
  "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](/ai/docker-agent/sharing-agents/) 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.

```yaml
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:

```yaml
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:

```console
$ 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?

- Utiliza la [MCP Gateway](/ai/mcp-catalog-and-toolkit/mcp-gateway/) para dar a tus
  agentes acceso a servidores MCP preconfigurados
- Explora servidores MCP de forma interactiva con el [MCP
  Toolkit](/ai/mcp-catalog-and-toolkit/)
- Revisa la [referencia de configuración](/ai/docker-agent/reference/config/) para configuraciones
  avanzadas de agentes
- Explora la [referencia de conjuntos de herramientas (toolsets)](/ai/docker-agent/reference/toolsets/) para saber qué herramientas
  pueden usar los agentes
- Añade [RAG para búsqueda en el código fuente](/ai/docker-agent/rag/) a tu agente
- Consulta la [referencia de CLI](/ai/docker-agent/reference/cli/) para ver todas las opciones de `docker agent serve mcp`
- Explora las [configuraciones de ejemplo](https://github.com/docker/docker-agent/tree/main/examples) para
  diferentes tipos de agentes