Skip to content

docker-gateway-tutorial.md

Latest commit

 

History

History
336 lines (236 loc) · 7.87 KB

docker-gateway-tutorial.md

File metadata and controls

336 lines (236 loc) · 7.87 KB
Raw

Tutorial de Docker Gateway MCP

ES | PT

Tutorial para configurar docker-gateway con servidores MCP ejecutándose dentro de contenedores Docker.

Versión: 1.0.0 Última Actualización: 2026-01-28

¿Qué es Docker Gateway?

Docker Gateway es un servidor MCP que actúa como un puente entre Claude Code y múltiples servidores MCP ejecutándose dentro de contenedores Docker.

Beneficio Clave: Sin Costo Extra de Tokens

Cuando los MCPs se ejecutan dentro de docker-gateway, sus definiciones de herramientas están encapsuladas en el contenedor. Esto significa:

Configuración Costo de Tokens Definiciones de Herramientas en Contexto
Directo en ~/.claude.json Cada MCP suma tokens Sí, todos los esquemas de herramientas visibles
Dentro de docker-gateway Sin costo extra Encapsuladas en el contenedor

¿Por qué? Claude Code solo ve las herramientas de docker-gateway (mcp-add, mcp-find, etc.), no las herramientas individuales de cada MCP interno. Las herramientas reales se invocan a través del gateway.

Requisitos Previos

  • Docker Desktop 4.37+ instalado y ejecutándose
  • CLI de Claude Code instalado
  • Claves API para los servicios MCP deseados

Paso 1: Inicializar Docker MCP Toolkit

# Inicializar el sistema de catálogo
docker mcp catalog init

# Verificar inicialización
docker mcp catalog ls

Salida esperada:

docker-mcp: Docker MCP Catalog

El catálogo contiene más de 313 servidores MCP disponibles para habilitar.

Paso 2: Explorar Servidores Disponibles

# Listar todos los servidores disponibles
docker mcp catalog show docker-mcp

# Buscar servidor específico
docker mcp catalog show docker-mcp | grep -i apify
docker mcp catalog show docker-mcp | grep -i exa

Paso 3: Habilitar Servidores MCP

# Habilitar servidores que deseas usar
docker mcp server enable apify-mcp-server
docker mcp server enable exa
docker mcp server enable context7

# Listar servidores habilitados
docker mcp server ls

Paso 4: Configurar Claves API

Método 1: Usando Docker MCP Secrets (puede tener bugs)

# Establecer secrets
docker mcp secret set APIFY_TOKEN "your-apify-token"
docker mcp secret set EXA_API_KEY "your-exa-api-key"

Método 2: Editar Archivo de Catálogo Directamente (solución recomendada)

Debido a un bug conocido (Dic 2025), los secrets pueden no pasar correctamente a los contenedores.

Solución alternativa: Editar ~/.docker/mcp/catalogs/docker-mcp.yaml directamente:

# Encuentra la entrada de tu MCP y agrega valores env
apify-mcp-server:
  env:
    - name: APIFY_TOKEN
      value: 'apify_api_xxxxxxxxxxxxx'
    - name: TOOLS
      value: 'actors,docs,apify/rag-web-browser'

exa:
  env:
    - name: EXA_API_KEY
      value: 'your-exa-api-key-here'

⚠️ Nota de seguridad: Esto expone credenciales en un archivo local. Establece permisos apropiados:

chmod 600 ~/.docker/mcp/catalogs/docker-mcp.yaml

Paso 5: Configurar Claude Code

Agregar docker-gateway a ~/.claude.json:

{
  "mcpServers": {
    "docker-gateway": {
      "type": "stdio",
      "command": "docker",
      "args": ["mcp", "gateway", "run"]
    }
  }
}

O usar el CLI de Claude:

claude mcp add docker-gateway -s user -- docker mcp gateway run

Paso 6: Verificar Configuración

# Verificar herramientas disponibles a través del gateway
docker mcp tools ls

# La salida esperada muestra herramientas del gateway + herramientas de servidores habilitados
# Ejemplo: 58 herramientas (7 del gateway + 51 de servidores habilitados)

En Claude Code:

# Listar estado de MCP
claude mcp list

# Debería mostrar:
# docker-gateway: docker mcp gateway run - ✓ Connected

Usando Docker Gateway

Herramientas del Gateway Disponibles

Herramienta Descripción
mcp-add Agregar servidor MCP a la sesión actual
mcp-find Buscar servidores en el catálogo
mcp-remove Eliminar servidor MCP de la sesión
mcp-exec Ejecutar herramienta de servidor habilitado
mcp-config-set Configurar ajustes del servidor MCP
code-mode Crear herramientas JavaScript combinadas
mcp-create-profile Guardar estado actual del gateway

Accediendo a Herramientas de Servidores Habilitados

Una vez habilitados los servidores, sus herramientas están disponibles a través del gateway:

# Herramientas de Apify (vía docker-gateway)
mcp__docker-gateway__search-actors
mcp__docker-gateway__call-actor
mcp__docker-gateway__apify-slash-rag-web-browser

# Herramientas de EXA (vía docker-gateway)
mcp__docker-gateway__web_search_exa
mcp__docker-gateway__company_research

# Herramientas de Context7 (vía docker-gateway)
mcp__docker-gateway__resolve-library-id
mcp__docker-gateway__query-docs

Ejemplo de Configuración Completa

~/.claude.json

{
  "mcpServers": {
    "desktop-commander": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@wonderwhy-er/desktop-commander"]
    },
    "docker-gateway": {
      "type": "stdio",
      "command": "docker",
      "args": ["mcp", "gateway", "run"]
    },
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-playwright"]
    }
  }
}

Resultado

User MCPs (4 servers):
├── desktop-commander  ✓ connected
├── docker-gateway     ✓ connected  (58 tools inside)
├── playwright         ✓ connected
└── n8n-mcp           ✓ connected

Inside docker-gateway:
├── apify-mcp-server   (7 tools)
├── exa                (8 tools)
├── context7           (2 tools)
└── + gateway tools    (7 tools)

Resolución de Problemas

El Gateway No Inicia

# Verificar que Docker está ejecutándose
docker info

# Verificar logs del gateway
docker mcp gateway run --verbose

Las Herramientas Muestran "(N prompts)" en Lugar de "(N tools)"

Esto indica fallo de autenticación. Usa la solución alternativa:

# Editar catálogo directamente con credenciales hardcoded
nano ~/.docker/mcp/catalogs/docker-mcp.yaml

Servidor No Encontrado

# Actualizar catálogo
docker mcp catalog update

# Verificar que el servidor existe
docker mcp catalog show docker-mcp | grep -i "server-name"

Reiniciar Todo

# Deshabilitar todos los servidores
docker mcp server reset

# Reiniciar catálogo
docker mcp catalog reset

# Re-inicializar
docker mcp catalog init

Mejores Prácticas

1. Usar docker-gateway para MCPs basados en API

Colocar estos dentro de docker-gateway (no necesitan acceso al host):

  • Apify (APIs de web scraping)
  • EXA (APIs de búsqueda)
  • Context7 (APIs de documentación)
  • Cualquier integración cloud/SaaS

2. Mantener MCPs con acceso al host directos

Mantener estos en ~/.claude.json directamente:

  • desktop-commander (necesita acceso a archivos/terminal del host)
  • playwright (necesita navegador del host)
  • MCPs de filesystem

3. Asegurar tus credenciales

# Establecer permisos restrictivos
chmod 600 ~/.docker/mcp/catalogs/docker-mcp.yaml
chmod 700 ~/.docker/mcp/

# Nunca hacer commit de estos archivos
echo "~/.docker/mcp/" >> ~/.gitignore_global

Documentación Relacionada

Tutorial de Docker Gateway MCP v1.0.0 - AIOX Framework