Despliega túneles MCP con Helm

El chart de Helm de Anthropic instala el stack de túnel como un único Deployment y lo conecta al túnel que creaste en la Console.

Antes de comenzar

Necesitas:

• Un túnel creado en la Console. Completa primero Crear un túnel y anota el ID del túnel (tnl_...). Para el aprovisionamiento manual también necesitas el token del túnel y el dominio del túnel de ese paso.
• Una forma de que el chart se autentique con 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 org:manage_tunnels.
  • Manual. Omite el acceso programático. Deberás obtener el token del túnel desde la Console, generar una CA y un certificado de servidor por tu cuenta, 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 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 clúster en las direcciones que configurarás en 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 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.

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 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

Restringe 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 de cloudflared hacia el edge 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 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.

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

Siempre pasa --version a helm upgrade para no obtener un chart más nuevo de forma inesperada.

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 1.0.0 \
  -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 las actualizaciones cuando se fuerza:

helm upgrade mcp-tunnel \
  oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \
  --version 1.0.0 \
  -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 el 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