Desplegar túneles MCP con Helm

El chart de Helm de Anthropic instala el stack de túneles como un único Deployment y lo conecta 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 conectarte a un túnel existente en su lugar, créalo en la Console y anota el ID del túnel (tnl_...). El aprovisionamiento manual siempre parte de un túnel creado en la Console; también necesitarás su token de túnel y su dominio de túnel.
• Una forma de que el chart se autentique ante la API de Tunnels.
  • 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. Deberás obtener el token del túnel desde la Console, generar tú mismo una CA y un certificado de servidor, registrar la CA en la Console y proporcionar 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 tunnel edge (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: Usar un servidor MCP de ejemplo

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



Instalar



Verificar 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 una solicitud a la API de Messages, donde <route> es una clave de gateway.config.routes y <path> es lo que sea que el servidor MCP upstream sirva en esa ruta. Con el servidor MCP de ejemplo, eso es https://echo.<your-tunnel-domain>/mcp. Consulta Usar los servidores MCP tunelizados para ver 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



Restringir el tráfico saliente con NetworkPolicy

El tráfico entrante al pod del proxy está denegado de forma predeterminada (networkPolicy.ingress.enabled: true). Para restringir adicionalmente el tráfico saliente 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 tráfico saliente desde cloudflared hacia el tunnel edge se permite por separado mediante networkPolicy.egress.cloudflaredEgressCIDRs.



Ajustar 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 ver 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.



Proporcionar 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

Siempre pasa --version a helm upgrade para no obtener inesperadamente un chart más reciente.



Actualizar desde 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 de túnel ya almacenado en el Secret mcp-tunnel al volver a ejecutarse), pero el cambio 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.



Cambiar 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.2 \
  -n mcp-tunnel \
  -f values.yaml



Rotar 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.2 \
  -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 detalles 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 sufijo -cert-renew) que ejecuta setup renew-cert diariamente (en serverCert.cronSchedule, predeterminado 0 0 * * * UTC). El job no hace nada 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 realiza 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 nuevo certificado de servidor 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