Despliega túneles MCP con Helm

El chart de Helm de Anthropic instala el stack de túnel como un único Deployment y lo adjunta a tu túnel: uno que el hook de configuración del chart crea por ti, o un túnel existente que creaste en la Console.



Antes de comenzar

Necesitas:

• Un túnel. Con acceso programático, el hook de configuración del chart 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; también necesitarás su token de túnel y el dominio del túnel.
• Una forma de que el chart se autentique ante la Tunnels API.
  • Acceso programático (recomendado). El componente de configuración se autentica mediante Workload Identity Federation, obtiene el token del túnel, genera una CA, la registra con Anthropic y almacena todo en un Secret. Necesitarás una regla de federación con alcance workspace:manage_tunnels.
  • 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 por tu cuenta, registrarás la CA en la Console y proporcionarás las credenciales al clúster como Secrets.
• Un clúster de Kubernetes en el que puedas desplegar con helm y kubectl. La pestaña Sin acceso programático también usa openssl (1.1.1 o posterior).
• Conectividad de red saliente desde el clúster 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 clúster en las direcciones que configurarás bajo gateway.config.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:

kubectl create namespace mcp-tunnel --dry-run=client -o yaml | kubectl apply -f -
kubectl -n mcp-tunnel apply -f - <<'EOF'
apiVersion: v1
kind: ConfigMap
metadata:
  name: hello-mcp-src
data:
  hello_server.py: |
    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")
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: hello-mcp
spec:
  replicas: 1
  selector:
    matchLabels: { app: hello-mcp }
  template:
    metadata:
      labels: { app: hello-mcp }
    spec:
      containers:
        - name: hello-mcp
          image: python:3.13-slim
          command: ["sh", "-c", "pip install --quiet mcp && python /app/hello_server.py"]
          volumeMounts:
            - { name: src, mountPath: /app }
          ports:
            - { containerPort: 9000 }
      volumes:
        - name: src
          configMap: { name: hello-mcp-src }
---
apiVersion: v1
kind: Service
metadata:
  name: hello-mcp
spec:
  selector: { app: hello-mcp }
  ports:
    - { port: 9000, targetPort: 9000 }
EOF

Los pasos de instalación que siguen indican dónde agregar la ruta correspondiente.



Instalación



Verifica el despliegue

Verifica de extremo a extremo desde el lado de Anthropic: usa https://<route>.<your-tunnel-domain>/<path> en una sesión de Managed Agent o en una solicitud de la Messages API, donde <route> es una clave de gateway.config.routes y <path> es lo que sirva el servidor MCP upstream. Con el servidor MCP de ejemplo, eso es https://echo.<your-tunnel-domain>/mcp. Consulta Usa los servidores MCP tunelizados para las formas de las solicitudes.

Si eso falla, revisa los logs del pod (kubectl -n mcp-tunnel logs deploy/mcp-tunnel -c mcp-proxy y -c cloudflared) y consulta Solución de problemas.



Configuración opcional



Restringe el egreso con NetworkPolicy

El ingreso al pod del proxy está denegado de forma predeterminada (networkPolicy.ingress.enabled: true). Para restringir adicionalmente el egreso del pod, establece networkPolicy.egress.enabled: true y completa networkPolicy.egress.mcpServers con selectores de etiquetas de pod o rangos CIDR que cubran tus servidores MCP upstream. El egreso desde cloudflared hacia el borde del túnel se permite por separado mediante networkPolicy.egress.cloudflaredEgressCIDRs.



Ajusta el proxy

Los campos bajo gateway.config.* se pasan directamente al archivo de configuración del proxy. Los ajustes comunes incluyen upstream.allowed_ips, log_level y upstream.tls. Consulta la referencia de configuración del proxy para la lista completa de campos. El chart siempre establece listen_addr, tls.cert_file y tls.key_file; establecerlos en gateway.config no tiene efecto.



Proporciona tu propio token OIDC

De forma predeterminada, el chart proyecta un token de ServiceAccount de Kubernetes para el componente de configuración. Para usar un token de un proveedor de identidad diferente (como SPIFFE, Vault o un sidecar de SDK de nube), móntalo con setup.extraVolumes y setup.extraVolumeMounts. Luego apunta api.wif.tokenFile a la ruta de montaje. El chart establece ANTHROPIC_IDENTITY_TOKEN_FILE en esa ruta, y el componente de configuración lee el token desde allí.



Actualizaciones

Pasa siempre --version a helm upgrade para no descargar un chart más nuevo inesperadamente.



Actualiza desde el chart 1.x

El chart 2.0.0 mueve el ID del túnel de api.wif.tunnelId a tunnel.id. Antes de actualizar, edita tu values.yaml: mueve el valor tnl_... a tunnel.id y elimina api.wif.tunnelId. Dejar tunnel.id sin establecer es seguro (el componente de configuración reutiliza el ID del túnel ya almacenado en el Secret mcp-tunnel al volver a ejecutarse), pero el movimiento explícito mantiene tu values.yaml preciso. También actualiza el alcance de tu regla de federación de org:manage_tunnels a workspace:manage_tunnels en la Console.



Cambia la configuración

Para cambios rutinarios como rutas, número de réplicas o NetworkPolicy:

helm upgrade mcp-tunnel \
  oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \
  --version 2.0.1 \
  -n mcp-tunnel \
  -f values.yaml



Rota el token del túnel

Con acceso programático, incrementa tunnel.tokenVersion en values.yaml y actualiza con --set setup.force=true. El componente de configuración solo se vuelve a ejecutar en actualizaciones cuando se fuerza:

helm upgrade mcp-tunnel \
  oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \
  --version 2.0.1 \
  -n mcp-tunnel \
  -f values.yaml \
  --set setup.force=true

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 detalle del túnel en la Console, luego actualiza el Secret mcp-tunnel-token:

kubectl -n mcp-tunnel create secret generic mcp-tunnel-token \
  --from-literal=tunnel-token='eyJ...' --dry-run=client -o yaml | kubectl apply -f -
kubectl -n mcp-tunnel rollout restart deploy/mcp-tunnel



Renovación de certificados

El chart proporciona automatización, pero sigues siendo responsable de monitorear la expiración y confirmar que la renovación se complete.

Con acceso programático, la renovación de certificados es automática. El chart despliega un CronJob (nombrado según el fullname de Helm, con el sufijo -cert-renew) que ejecuta setup renew-cert diariamente (en serverCert.cronSchedule, predeterminado 0 0 * * * UTC). El job no tiene efecto a menos que el certificado esté dentro de serverCert.renewBefore de su expiración (predeterminado 30 días). La renovación es local: el job firma un certificado nuevo con la CA ya almacenada en el Secret, no hace llamadas a la API y solo necesita el RBAC de Kubernetes que el chart otorga. El proxy recarga en caliente el certificado desde el montaje del Secret, por lo que no se necesita reiniciar el Deployment.

Sin acceso programático no hay CronJob. Desde dentro del directorio mcp-tunnel/ que conservaste después de la instalación, firma un certificado de servidor nuevo con la CA existente (no regeneres la CA):

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

kubectl -n mcp-tunnel create secret generic mcp-tunnel-cert \
  --from-file=tls.crt=data/tls.crt --from-file=tls.key=data/tls.key \
  --dry-run=client -o yaml | kubectl apply -f -

El proxy recarga en caliente el certificado desde el montaje del Secret.



Próximos pasos