MensajesTúneles MCP

Despliega túneles MCP con Docker Compose

Instala el stack de túneles MCP en una VM usando Docker Compose.

Los túneles MCP están en vista previa de investigación. Solicita acceso para probarlos.

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

Antes de comenzar

Necesitas:

Un túnel. Con acceso programático, el componente de configuración crea uno por ti cuando no proporcionas un ID de túnel; para adjuntarte a un túnel existente en su lugar, créalo en la Console y registra el ID del túnel (tnl_...). El aprovisionamiento manual siempre comienza desde un túnel creado en la Console.
Una forma de que el host se autentique ante la Tunnels API.
- Acceso programático (recomendado). Activa Set up programmatic access al crear el túnel (o crea la regla de federación directamente en Settings > Workload identity si estás dejando que el componente de configuración cree el túnel) para que el componente de configuración pueda autenticarse mediante Workload Identity Federation. Registra el ID de la regla de federación (fdrl_...) y tu ID de organización.
- Manual. Omite el acceso programático. Obtendrás el token del túnel desde la Console, generarás una CA y un certificado de servidor tú mismo, y registrarás la CA en la Console.
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 borde 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 bajo routes. Si aún no tienes uno, usa el servidor de ejemplo.

Opcional: Usa un servidor MCP de ejemplo

Si no tienes un servidor MCP disponible para pruebas, usa este 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 a 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.

Esta ruta requiere que el host tenga un proveedor de identidad OIDC (como un servidor de metadatos de VM en la nube o SPIFFE). Si no lo tiene, usa la pestaña Without programmatic access en su lugar.

El componente de configuración usa Workload Identity Federation para obtener el token del túnel, generar una CA y un certificado de servidor, y registrar la CA con Anthropic.

Prepare the deployment directory
mkdir -p mcp-tunnel/{config,data} cd mcp-tunnel sudo chown 65532:65532 data
Los contenedores se ejecutan como el UID no root 65532 y necesitan acceso de escritura a data/.

Write docker-compose.yaml

El archivo compose fija las imágenes por digest SHA-256, ejecuta cada contenedor como no root con un sistema de archivos de solo lectura, elimina todas las capacidades de Linux y deshabilita la escalada de privilegios.

cat > docker-compose.yaml <<'EOF'
services:
  setup:
    image: us-docker.pkg.dev/anthropic-public-registry/images/mcp-proxy@sha256:9d4c80593b559fc3ca3814866418744fa94858b02a4d4a4cc52d423e732ccc81
    entrypoint: ["/setup"]
    command:
      - init
      - --api-url=https://api.anthropic.com
      - --output=dir:/data
      - --token-version=1
    environment:
      - TUNNEL_ID
      - ANTHROPIC_FEDERATION_RULE_ID
      - ANTHROPIC_ORGANIZATION_ID
      - ANTHROPIC_WORKSPACE_ID
      - ANTHROPIC_IDENTITY_TOKEN
    volumes:
      - ./data:/data
    user: "65532:65532"
    read_only: true
    security_opt:
      - no-new-privileges:true
    cap_drop:
      - ALL
    profiles: ["setup"]

  cloudflared:
    image: cloudflare/cloudflared@sha256:6b599ca3e974349ead3286d178da61d291961182ec3fe9c505e1dd02c8ac31b0
    command: tunnel --no-autoupdate run --url http://localhost:8080
    environment:
      - TUNNEL_TOKEN
    # Comparte el netns del proxy para que localhost:8080 lo alcance.
    network_mode: "service:mcp-proxy"
    restart: unless-stopped
    user: "65532:65532"
    read_only: true
    security_opt:
      - no-new-privileges:true
    cap_drop:
      - ALL
    stop_grace_period: 30s
    logging:
      options:
        max-size: "10m"
        max-file: "3"

  mcp-proxy:
    image: us-docker.pkg.dev/anthropic-public-registry/images/mcp-proxy@sha256:9d4c80593b559fc3ca3814866418744fa94858b02a4d4a4cc52d423e732ccc81
    volumes:
      - ./config/mcp-proxy.yaml:/etc/mcp-gateway/config.yaml:ro
      - ./data:/data:ro
    restart: unless-stopped
    user: "65532:65532"
    read_only: true
    security_opt:
      - no-new-privileges:true
    cap_drop:
      - ALL
    stop_grace_period: 30s
    logging:
      options:
        max-size: "10m"
        max-file: "3"
EOF

Si estás usando el servidor MCP de ejemplo, agrégalo como un servicio:

cat >> docker-compose.yaml <<'EOF'

  hello-mcp:
    image: python:3.13-slim
    working_dir: /app
    volumes:
      - ./hello_server.py:/app/hello_server.py:ro
    command: sh -c "pip install --quiet mcp && python hello_server.py"
    restart: unless-stopped
EOF

Provision the tunnel
Establece los identificadores. Deja TUNNEL_ID sin definir para que el componente de configuración cree un túnel; defínelo para adjuntarte a un túnel existente desde la Console:
# export TUNNEL_ID=tnl_... # configúralo para conectarte a un túnel existente export ANTHROPIC_FEDERATION_RULE_ID=fdrl_... export ANTHROPIC_ORGANIZATION_ID=00000000-0000-0000-0000-000000000000
Si tu regla de federación está limitada a un workspace distinto del predeterminado de tu organización, establece también ANTHROPIC_WORKSPACE_ID=wrkspc_...; de lo contrario, el componente de configuración usa el workspace predeterminado. Un túnel creado automáticamente se crea en ese workspace.
Establece ANTHROPIC_IDENTITY_TOKEN con un JWT OIDC del proveedor de identidad de este host. Sigue la guía de WIF para tu proveedor para registrar el emisor, establecer el subject de la regla y emitir el token; la audiencia de la regla debe coincidir con la audiencia que solicitas al emitir el token.
Ejecuta el componente de configuración:
docker compose run --rm setup
setup init es idempotente sobre data/: volver a ejecutarlo reutiliza el ID del túnel y la CA ya almacenados allí y nunca crea un segundo túnel. Una nueva CA se genera y registra solo cuando data/ está vacío o TUNNEL_ID ha cambiado; en ese caso aplica el límite de dos certificados activos, así que revoca uno en la Console primero si ambos espacios están ocupados.
Consulta Fallos de autenticación del componente de configuración si produce errores.
Recupera tu dominio de túnel y expórtalo para los pasos posteriores:
export TUNNEL_DOMAIN=$(sudo cat data/tunnel-domain) echo "$TUNNEL_DOMAIN"
Los tokens de Workload Identity Federation son de corta duración (1 hora por defecto) y expiran automáticamente; no hay nada que revocar después de que la configuración se complete.
Write the proxy config
tunnel_domain es obligatorio: el proxy lo usa para eliminar el sufijo de dominio de los nombres de host entrantes antes de buscar el subdominio en routes. routes es un mapa plano de subdominio a URL upstream, no una lista.
cat > config/mcp-proxy.yaml <<EOF listen_addr: ":8080" log_level: info shutdown_timeout: 30s tunnel_domain: ${TUNNEL_DOMAIN} tls: cert_file: /data/tls.crt key_file: /data/tls.key routes: echo: http://hello-mcp:9000 EOF
La ruta echo: apunta al servidor MCP de ejemplo; reemplázala con (o agrega) tus propias rutas. Consulta la referencia de configuración del proxy para ver todos los campos disponibles.

Start the deployment

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

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 multi-VM, 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 Console. El mismo token de túnel y los mismos certificados funcionan en todas las réplicas.

Verifica el despliegue

Verifica de extremo a extremo llamando a un servidor MCP upstream desde el lado de Anthropic: consulta Usa 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/.

Rota 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, emite un JWT OIDC nuevo 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 de setup se niega a rotar cuando el valor
# no ha cambiado.

# export TUNNEL_ID=tnl_...   # configúralo solo si lo configuraste durante la instalación
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 emitir 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 Console, luego actualiza la variable de entorno TUNNEL_TOKEN en cada host y reinicia cloudflared (docker compose up -d cloudflared).

Hacer clic en Rotate token invalida el token actual de inmediato. Entre ese momento y la actualización de TUNNEL_TOKEN en cada host y el reinicio de cloudflared, cualquier host cuyo cloudflared se reinicie (fallo, reinicio del host) no puede reconectarse. Actualiza cada host con prontitud después de rotar.

Renovación de certificados

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

Con acceso programático:

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

Los argumentos de la 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.

Pasa --renew-before=720h para que el comando no haga nada cuando queden más de 30 días de validez. Esto hace que sea seguro ejecutarlo en un horario fijo.

Sin acceso programático, firma un nuevo certificado de servidor con tu CA existente (la CA registrada en la Console 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

Usa los servidores MCP tunelizados

Adjunta un servidor MCP upstream a un Managed Agent o a la Messages API.

Seguridad

Guía de refuerzo, rotación de credenciales y respuesta ante brechas.

Solución de problemas

Diagnostica problemas de conectividad, TLS y enrutamiento.

Was this page helpful?

MensajesTúneles MCP

Despliega túneles MCP con Docker Compose

Instala el stack de túneles MCP en una VM usando Docker Compose.

Los túneles MCP están en vista previa de investigación. Solicita acceso para probarlos.

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

Antes de comenzar

Necesitas:

Un túnel. Con acceso programático, el componente de configuración crea uno por ti cuando no proporcionas un ID de túnel; para adjuntarte a un túnel existente en su lugar, créalo en la Console y registra el ID del túnel (tnl_...). El aprovisionamiento manual siempre comienza desde un túnel creado en la Console.
Una forma de que el host se autentique ante la Tunnels API.
- Acceso programático (recomendado). Activa Set up programmatic access al crear el túnel (o crea la regla de federación directamente en Settings > Workload identity si estás dejando que el componente de configuración cree el túnel) para que el componente de configuración pueda autenticarse mediante Workload Identity Federation. Registra el ID de la regla de federación (fdrl_...) y tu ID de organización.
- Manual. Omite el acceso programático. Obtendrás el token del túnel desde la Console, generarás una CA y un certificado de servidor tú mismo, y registrarás la CA en la Console.
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 borde 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 bajo routes. Si aún no tienes uno, usa el servidor de ejemplo.

Opcional: Usa un servidor MCP de ejemplo

Si no tienes un servidor MCP disponible para pruebas, usa este 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 a 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 componente de configuración usa Workload Identity Federation para obtener el token del túnel, generar una CA y un certificado de servidor, y registrar la CA con Anthropic.

Prepare the deployment directory
mkdir -p mcp-tunnel/{config,data} cd mcp-tunnel sudo chown 65532:65532 data
Los contenedores se ejecutan como el UID no root 65532 y necesitan acceso de escritura a data/.

Write docker-compose.yaml

cat > docker-compose.yaml <<'EOF'
services:
  setup:
    image: us-docker.pkg.dev/anthropic-public-registry/images/mcp-proxy@sha256:9d4c80593b559fc3ca3814866418744fa94858b02a4d4a4cc52d423e732ccc81
    entrypoint: ["/setup"]
    command:
      - init
      - --api-url=https://api.anthropic.com
      - --output=dir:/data
      - --token-version=1
    environment:
      - TUNNEL_ID
      - ANTHROPIC_FEDERATION_RULE_ID
      - ANTHROPIC_ORGANIZATION_ID
      - ANTHROPIC_WORKSPACE_ID
      - ANTHROPIC_IDENTITY_TOKEN
    volumes:
      - ./data:/data
    user: "65532:65532"
    read_only: true
    security_opt:
      - no-new-privileges:true
    cap_drop:
      - ALL
    profiles: ["setup"]

  cloudflared:
    image: cloudflare/cloudflared@sha256:6b599ca3e974349ead3286d178da61d291961182ec3fe9c505e1dd02c8ac31b0
    command: tunnel --no-autoupdate run --url http://localhost:8080
    environment:
      - TUNNEL_TOKEN
    # Comparte el netns del proxy para que localhost:8080 lo alcance.
    network_mode: "service:mcp-proxy"
    restart: unless-stopped
    user: "65532:65532"
    read_only: true
    security_opt:
      - no-new-privileges:true
    cap_drop:
      - ALL
    stop_grace_period: 30s
    logging:
      options:
        max-size: "10m"
        max-file: "3"

  mcp-proxy:
    image: us-docker.pkg.dev/anthropic-public-registry/images/mcp-proxy@sha256:9d4c80593b559fc3ca3814866418744fa94858b02a4d4a4cc52d423e732ccc81
    volumes:
      - ./config/mcp-proxy.yaml:/etc/mcp-gateway/config.yaml:ro
      - ./data:/data:ro
    restart: unless-stopped
    user: "65532:65532"
    read_only: true
    security_opt:
      - no-new-privileges:true
    cap_drop:
      - ALL
    stop_grace_period: 30s
    logging:
      options:
        max-size: "10m"
        max-file: "3"
EOF

Si estás usando el servidor MCP de ejemplo, agrégalo como un servicio:

cat >> docker-compose.yaml <<'EOF'

  hello-mcp:
    image: python:3.13-slim
    working_dir: /app
    volumes:
      - ./hello_server.py:/app/hello_server.py:ro
    command: sh -c "pip install --quiet mcp && python hello_server.py"
    restart: unless-stopped
EOF

Provision the tunnel
Establece los identificadores. Deja TUNNEL_ID sin definir para que el componente de configuración cree un túnel; defínelo para adjuntarte a un túnel existente desde la Console:
# export TUNNEL_ID=tnl_... # configúralo para conectarte a un túnel existente export ANTHROPIC_FEDERATION_RULE_ID=fdrl_... export ANTHROPIC_ORGANIZATION_ID=00000000-0000-0000-0000-000000000000
Si tu regla de federación está limitada a un workspace distinto del predeterminado de tu organización, establece también ANTHROPIC_WORKSPACE_ID=wrkspc_...; de lo contrario, el componente de configuración usa el workspace predeterminado. Un túnel creado automáticamente se crea en ese workspace.
Establece ANTHROPIC_IDENTITY_TOKEN con un JWT OIDC del proveedor de identidad de este host. Sigue la guía de WIF para tu proveedor para registrar el emisor, establecer el subject de la regla y emitir el token; la audiencia de la regla debe coincidir con la audiencia que solicitas al emitir el token.
Ejecuta el componente de configuración:
docker compose run --rm setup
setup init es idempotente sobre data/: volver a ejecutarlo reutiliza el ID del túnel y la CA ya almacenados allí y nunca crea un segundo túnel. Una nueva CA se genera y registra solo cuando data/ está vacío o TUNNEL_ID ha cambiado; en ese caso aplica el límite de dos certificados activos, así que revoca uno en la Console primero si ambos espacios están ocupados.
Consulta Fallos de autenticación del componente de configuración si produce errores.
Recupera tu dominio de túnel y expórtalo para los pasos posteriores:
export TUNNEL_DOMAIN=$(sudo cat data/tunnel-domain) echo "$TUNNEL_DOMAIN"
Los tokens de Workload Identity Federation son de corta duración (1 hora por defecto) y expiran automáticamente; no hay nada que revocar después de que la configuración se complete.
Write the proxy config
tunnel_domain es obligatorio: el proxy lo usa para eliminar el sufijo de dominio de los nombres de host entrantes antes de buscar el subdominio en routes. routes es un mapa plano de subdominio a URL upstream, no una lista.
cat > config/mcp-proxy.yaml <<EOF listen_addr: ":8080" log_level: info shutdown_timeout: 30s tunnel_domain: ${TUNNEL_DOMAIN} tls: cert_file: /data/tls.crt key_file: /data/tls.key routes: echo: http://hello-mcp:9000 EOF
La ruta echo: apunta al servidor MCP de ejemplo; reemplázala con (o agrega) tus propias rutas. Consulta la referencia de configuración del proxy para ver todos los campos disponibles.

Start the deployment

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

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.

Verifica el despliegue

Actualizaciones

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

Rota el token del túnel

# 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 de setup se niega a rotar cuando el valor
# no ha cambiado.

# export TUNNEL_ID=tnl_...   # configúralo solo si lo configuraste durante la instalación
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 emitir 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

Renovación de certificados

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

Con acceso programático:

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

Los argumentos de la 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.

Pasa --renew-before=720h para que el comando no haga nada cuando queden más de 30 días de validez. Esto hace que sea seguro ejecutarlo en un horario fijo.

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

Usa los servidores MCP tunelizados

Adjunta un servidor MCP upstream a un Managed Agent o a la Messages API.

Seguridad

Guía de refuerzo, rotación de credenciales y respuesta ante brechas.

Solución de problemas

Diagnostica problemas de conectividad, TLS y enrutamiento.

Was this page helpful?

Antes de comenzar

Opcional: Usa un servidor MCP de ejemplo

Instalación

Verifica el despliegue

Actualizaciones

Rota el token del túnel

Renovación de certificados

Próximos pasos

Antes de comenzar

Opcional: Usa un servidor MCP de ejemplo

Instalación

Verifica el despliegue

Actualizaciones

Rota el token del túnel

Renovación de certificados

Próximos pasos

Antes de comenzar

Opcional: Usa un servidor MCP de ejemplo

Instalación

Verifica el despliegue

Actualizaciones

Rota el token del túnel

Renovación de certificados

Próximos pasos

Antes de comenzar

Opcional: Usa un servidor MCP de ejemplo

Instalación

Verifica el despliegue

Actualizaciones

Rota el token del túnel

Renovación de certificados

Próximos pasos