Desplegar túneles MCP con Docker Compose

Esta guía despliega el stack de túneles como contenedores reforzados en un único host. La misma configuración puede replicarse en varios hosts para lograr disponibilidad.

Antes de comenzar

Necesitas:

• Un túnel creado en la Consola. Sigue Crear un túnel y anota el ID del túnel (tnl_...).
• Una forma de que el host se autentique ante la API de Túneles.
  • Acceso programático (recomendado). Activa Set up programmatic access al crear el túnel para que el componente de configuración pueda autenticarse mediante Workload Identity Federation. Anota el ID de la regla de federación (fdrl_...) y el ID de tu organización.
  • Manual. Omite el acceso programático. Deberás obtener el token del túnel desde la Consola, generar tú mismo una CA y un certificado de servidor, y registrar la CA en la Consola.
• Un host con Docker y Docker Compose instalados. El flujo manual también requiere openssl (1.1.1 o posterior).
• Conectividad de red saliente desde el host hacia api.anthropic.com (443 TCP) y el edge del túnel (7844 TCP y UDP). Consulta los requisitos de red completos.
• Uno o más servidores MCP en ejecución y accesibles desde el host en las direcciones que configurarás en routes. Si aún no tienes uno, usa el servidor de ejemplo.

Opcional: Usar un servidor MCP de ejemplo

Si no tienes un servidor MCP disponible para pruebas, usa este servidor mínimo:

mkdir -p mcp-tunnel
cat > mcp-tunnel/hello_server.py <<'EOF'
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("hello-server", host="0.0.0.0", port=9000)


@mcp.tool()
def hello(name: str = "world") -> str:
    """Say hello to someone."""
    return f"Hello, {name}!"


if __name__ == "__main__":
    mcp.run(transport="streamable-http")
EOF

Los siguientes pasos de instalación hacen cd en mcp-tunnel/ e indican dónde agregar el servicio y la ruta correspondientes.

Instalación

Esta guía proporciona un enfoque de referencia usando Docker Compose. Eres responsable de adaptarlo para cumplir con los requisitos de seguridad de tu organización.

El archivo compose lee TUNNEL_TOKEN del entorno del host sin valor predeterminado, por lo que el export debe repetirse en cada shell nueva y después de un reinicio.

Para un despliegue en múltiples VMs, copia el directorio mcp-tunnel/ a cada host, establece TUNNEL_TOKEN y ejecuta docker compose up -d. En el flujo programático, TUNNEL_TOKEN es $(sudo cat data/tunnel-token); en el flujo manual es el valor que copiaste de la Consola. El mismo token de túnel y los mismos certificados funcionan en todas las réplicas.

Verificar el despliegue

Verifica de extremo a extremo llamando a un servidor MCP upstream desde el lado de Anthropic: consulta Usar los servidores MCP tunelizados. Con el servidor MCP de ejemplo, la URL enrutada es https://echo.<your-tunnel-domain>/mcp. Si la verificación falla, consulta Solución de problemas.

Actualizaciones

Ejecuta los comandos de esta sección desde dentro del directorio de despliegue mcp-tunnel/.

Rotar el token del túnel

Con acceso programático, incrementa --token-version en el comando del servicio setup, establece los identificadores de Workload Identity Federation, genera un nuevo JWT OIDC y vuelve a ejecutar el componente de configuración:

# Edita docker-compose.yaml: incrementa el entero en el argumento
# --token-version del servicio setup (por ejemplo, de --token-version=1 a
# --token-version=2). El binario setup se niega a rotar cuando el valor
# no ha cambiado.

export TUNNEL_ID=tnl_...
export ANTHROPIC_FEDERATION_RULE_ID=fdrl_...
export ANTHROPIC_ORGANIZATION_ID=00000000-0000-0000-0000-000000000000
# export ANTHROPIC_WORKSPACE_ID=wrkspc_...   # si tu regla tiene alcance de workspace
# Vuelve a generar ANTHROPIC_IDENTITY_TOKEN según la guía del proveedor WIF para tu
# entorno (habrá expirado desde la instalación).
export ANTHROPIC_IDENTITY_TOKEN=...

docker compose run --rm setup

export TUNNEL_TOKEN=$(sudo cat data/tunnel-token)
docker compose up -d cloudflared

El argumento --token-version se edita en docker-compose.yaml en lugar de pasarse en la línea de comandos para que el nuevo valor persista en futuras ejecuciones del componente de configuración. El componente de configuración se autentica con Workload Identity Federation; no hay ningún token de API que revocar.

Sin acceso programático, haz clic en Rotate token en la página de detalles del túnel en la Consola, luego actualiza la variable de entorno TUNNEL_TOKEN en cada host y reinicia cloudflared (docker compose up -d cloudflared).

Renovación de certificados

Eres responsable de monitorear la expiración y renovar el certificado de servidor antes de que expire.

Con acceso programático:

docker compose run --rm setup renew-cert --output=dir:/data

Los argumentos de CLI reemplazan el command del servicio setup (los argumentos de init) pero mantienen su entrypoint, por lo que esto ejecuta /setup renew-cert --output=dir:/data.

Sin acceso programático, firma un nuevo certificado de servidor con tu CA existente (la CA registrada en la Consola no cambia) y reemplaza data/tls.crt. Establece TUNNEL_DOMAIN primero si estás ejecutando esto desde una shell nueva.

export TUNNEL_DOMAIN=YOUR_TUNNEL_DOMAIN_HERE
openssl req -new -key data/tls.key -out /tmp/server.csr \
  -subj "/CN=${TUNNEL_DOMAIN}"
openssl x509 -req -in /tmp/server.csr \
  -CA data/ca.crt -CAkey data/ca.key -CAcreateserial \
  -out data/tls.crt -days 90 \
  -extfile data/tls.ext

En cualquiera de los dos flujos, el proxy sondea tls.cert_file y lo recarga automáticamente, por lo que no se requiere reinicio.

Próximos pasos