--- title: Implementar túneles MCP con Helm url: https://platform.claude.com/docs/es/agents-and-tools/mcp-tunnels/deploy-helm description: Instala la pila de túneles en un clúster de Kubernetes usando el chart de Helm de Anthropic. --- Los "MCP tunnels" (túneles de MCP) están en "research preview" (vista previa de investigación). [Solicita acceso](https://claude.com/form/mcp-tunnels) para probarlos. El chart de Helm de Anthropic instala la [pila de túneles](https://platform.claude.com/docs/es/agents-and-tools/mcp-tunnels/concepts#components) como un único Deployment y la 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 [Claude Console](https://platform.claude.com/docs/es/agents-and-tools/mcp-tunnels/console#create-a-tunnel). ## Antes de empezar 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](https://platform.claude.com/docs/es/agents-and-tools/mcp-tunnels/console#create-a-tunnel) y anota el ID del túnel (`tnl_...`). El aprovisionamiento manual siempre parte de un túnel creado en la Console; también necesitas 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](https://platform.claude.com/docs/es/agents-and-tools/mcp-tunnels/concepts#credential-provisioning) (recomendado).** El [componente de configuración](https://platform.claude.com/docs/es/agents-and-tools/mcp-tunnels/concepts#components) 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. Necesitas una regla de federación con el alcance `workspace:manage_tunnels`. * **[Manual](https://platform.claude.com/docs/es/agents-and-tools/mcp-tunnels/concepts#credential-provisioning).** Omite el acceso programático. [Obtendrás el token del túnel desde la Console](https://platform.claude.com/docs/es/agents-and-tools/mcp-tunnels/console#get-the-connection-details), generarás tú mismo una CA y un certificado de servidor, [registrarás la CA en la Console](https://platform.claude.com/docs/es/agents-and-tools/mcp-tunnels/console#add-a-ca-certificate) y proporcionarás las credenciales al clúster como Secrets. * **Un clúster de Kubernetes** en el que puedas implementar 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](https://platform.claude.com/docs/es/agents-and-tools/mcp-tunnels/concepts#components) (7844 TCP y UDP). Consulta los [requisitos de red](https://platform.claude.com/docs/es/agents-and-tools/mcp-tunnels/overview#network-requirements) 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](https://platform.claude.com/docs/es/agents-and-tools/mcp-tunnels/deploy-helm#optional-use-a-sample-mcp-server). ## Opcional: Usa un servidor MCP de ejemplo Si no tienes un servidor MCP disponible para pruebas, usa este mínimo: ```bash 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 El componente de configuración intercambia el token proyectado de ServiceAccount del clúster a través de tu regla de federación, obtiene el token del túnel, genera una CA y un certificado de servidor, y registra la CA con Anthropic. Un CronJob diario renueva el certificado de servidor según sea necesario, por lo que no manejas ningún secreto a mano. Sigue [Usar WIF con Kubernetes](https://platform.claude.com/docs/es/manage-claude/wif-providers/kubernetes) para registrar el emisor OIDC de tu clúster y crear una regla de federación. El componente de configuración se ejecuta con su propia ServiceAccount en el namespace de la release; el nombre exacto sigue la convención `fullname` de Helm, así que para cualquier nombre de release distinto de `mcp-tunnel`, ejecuta `helm template ... | grep -A2 'kind: ServiceAccount'` para confirmarlo antes de crear la regla. El resto de esta guía asume el nombre de release `mcp-tunnel` en el namespace `mcp-tunnel`, donde la ServiceAccount es `mcp-tunnel-setup`. | Campo | Valor | | -------- | -------------------------------------------------------------------- | | Subject | `system:serviceaccount:mcp-tunnel:mcp-tunnel-setup` | | Audience | `api.anthropic.com` (el valor predeterminado del chart; sin esquema) | | Scope | `workspace:manage_tunnels` | La audiencia predeterminada del chart es `api.anthropic.com` sin esquema, pero el formulario de reglas de federación de la Console sugiere `https://api.anthropic.com`. Ambos deben coincidir byte por byte o la autenticación falla. Establece la audiencia de la regla en `api.anthropic.com`, o establece `api.wif.audience` en `values.yaml` como `https://api.anthropic.com`. Si el túnel está en un workspace distinto del predeterminado de la organización, también [agrega la cuenta de servicio de la regla a ese workspace](https://platform.claude.com/docs/es/manage-claude/workspaces#role-inheritance) (la API de Tunnels autoriza según las membresías de workspace de la cuenta de servicio). Anota el ID de la regla (`fdrl_...`); lo establecerás como `api.wif.federationRuleId`. El CronJob diario de renovación de certificados usa una ServiceAccount separada (también derivada del `fullname` de Helm), pero no llama a la API de Tunnels; renueva el certificado localmente y solo necesita RBAC de Kubernetes, que el chart otorga. La regla de federación no necesita cubrirla. ```bash helm show values \ oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \ --version 2.1.0 > values.yaml ``` Edita `values.yaml` y establece las claves `api.wif.*` con el ID de la regla de federación y el ID de la organización, además de una entrada en `routes` para cada [servidor MCP upstream](https://platform.claude.com/docs/es/agents-and-tools/mcp-tunnels/concepts#components): ```yaml values.yaml api: wif: federationRuleId: "fdrl_..." organizationId: "00000000-0000-0000-0000-000000000000" # Set when the tunnel is in a non-default workspace and the # rule's service account is a member of that workspace. # workspaceId: "wrkspc_..." tunnel: # Leave empty to have the setup hook create a tunnel during install. # Set to attach to an existing tunnel from the Console. id: "" # Increment to rotate the tunnel token on the next upgrade. # See the "Rotate the tunnel token" section. tokenVersion: "1" gateway: config: routes: docs: http://docs-mcp.internal:8080 search: http://search-mcp.internal:8080 ``` Con estas rutas, Claude llega a los servidores en `docs.` y `search.`. Algunas distribuciones administradas de Kubernetes asignan el CIDR de Service fuera de los rangos privados estándar; si tus rutas apuntan a Services dentro del clúster, agrega aquí `gateway.config.upstream.allowed_ips` como se describe en [Validación de IP upstream](https://platform.claude.com/docs/es/agents-and-tools/mcp-tunnels/troubleshooting#upstream-ip-validation). Si estás usando el [servidor MCP de ejemplo](https://platform.claude.com/docs/es/agents-and-tools/mcp-tunnels/deploy-helm#optional-use-a-sample-mcp-server), establece `routes` como `echo: http://hello-mcp:9000` en su lugar. Renderiza el chart y revisa la salida según las prácticas de verificación de tu organización: ```bash helm template mcp-tunnel \ oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \ --version 2.1.0 \ -n mcp-tunnel \ -f values.yaml > rendered.yaml ``` ```bash helm install mcp-tunnel \ oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \ --version 2.1.0 \ --namespace mcp-tunnel --create-namespace \ -f values.yaml ``` El componente de configuración se ejecuta como un Job de hook pre-install de Helm, por lo que `helm install` se bloquea hasta que termina. Si tiene éxito, Helm elimina el Job automáticamente. Si `helm install` falla con un error de hook, consulta [Fallos de autenticación del componente de configuración](https://platform.claude.com/docs/es/agents-and-tools/mcp-tunnels/troubleshooting#setup-component-authentication-failures). Cuando `tunnel.id` está vacío, el componente de configuración crea el túnel en el workspace al que apunta tu regla de federación (el workspace predeterminado de la organización, a menos que establezcas `api.wif.workspaceId`) y almacena su ID y dominio en el Secret `mcp-tunnel`. Encuentra el dominio que necesitarás para la [verificación](https://platform.claude.com/docs/es/agents-and-tools/mcp-tunnels/deploy-helm#verify-the-deployment) en la página de detalles del túnel, que abres desde la página [MCP tunnels](https://platform.claude.com/settings/workspaces/default/mcp-tunnels) (`platform.claude.com/settings/workspaces/default/mcp-tunnels`) en la Console. En el selector de workspace de la barra lateral, selecciona el workspace que contiene el túnel. También puedes leer el dominio desde el Secret: ```bash kubectl -n mcp-tunnel get secret mcp-tunnel \ -o jsonpath='{.data.tunnel-domain}' | base64 -d ``` Volver a ejecutar el componente de configuración (durante [actualizaciones](https://platform.claude.com/docs/es/agents-and-tools/mcp-tunnels/deploy-helm#upgrades) o la [rotación del token](https://platform.claude.com/docs/es/agents-and-tools/mcp-tunnels/deploy-helm#rotate-the-tunnel-token)) reutiliza el ID del túnel almacenado en este Secret; nunca crea un segundo túnel. Los valores `api.wif.*` son identificadores, no secretos, por lo que almacenarlos en los Secrets del historial de releases de Helm no representa un riesgo. Los datos sensibles en reposo son el Secret `mcp-tunnel` que crea el componente de configuración, que contiene el token del túnel y las claves privadas TLS. Aplica a este namespace las prácticas estándar de tu organización para proteger Secrets de Kubernetes. En este modo (`setup.enabled: false`) el chart no realiza llamadas a la API; el componente de configuración no se ejecuta y no hay CronJob cert-renew. Usa esta ruta si prefieres no configurar Workload Identity Federation. [Crea el túnel](https://platform.claude.com/docs/es/agents-and-tools/mcp-tunnels/console#create-a-tunnel) y [obtén el token del túnel desde la Console](https://platform.claude.com/docs/es/agents-and-tools/mcp-tunnels/console#get-the-connection-details). Anota el dominio del túnel desde la página de detalles. Lo establecerás como `gateway.config.tunnel_domain`. El proxy escucha en WebSocket sin cifrar, con [TLS interno](https://platform.claude.com/docs/es/agents-and-tools/mcp-tunnels/concepts#components) transportado dentro de ese flujo usando el certificado que generas aquí. El SAN del certificado de servidor debe incluir `*.` como se describe en los [requisitos de certificados](https://platform.claude.com/docs/es/agents-and-tools/mcp-tunnels/reference#certificate-requirements). ```bash export TUNNEL_DOMAIN=YOUR_TUNNEL_DOMAIN_HERE mkdir -p mcp-tunnel/data cd mcp-tunnel # CA autofirmada. Extensiones explícitas para que cumpla los requisitos # del certificado sin importar los valores predeterminados de openssl.cnf de la distro. openssl req -x509 -newkey rsa:2048 -nodes \ -keyout data/ca.key -out data/ca.crt \ -days 3650 -subj "/CN=mcp-tunnel-ca" \ -addext "basicConstraints=critical,CA:TRUE" \ -addext "keyUsage=critical,keyCertSign,cRLSign" \ -addext "subjectKeyIdentifier=hash" # Archivo de extensiones para el certificado del servidor. Usar -extfile (en lugar de # -copy_extensions, que solo existe en OpenSSL 3.0+) permite que funcione en # OpenSSL 1.1.x. cat > data/tls.ext < El chart lee claves específicas; los nombres de los Secrets son configurables, pero las claves no. El siguiente comando de creación del namespace no hace nada si el namespace ya existe (por ejemplo, desde el paso del [servidor MCP de ejemplo](https://platform.claude.com/docs/es/agents-and-tools/mcp-tunnels/deploy-helm#optional-use-a-sample-mcp-server)). ```bash kubectl create namespace mcp-tunnel --dry-run=client -o yaml | kubectl apply -f - kubectl -n mcp-tunnel create secret generic mcp-tunnel-token \ --from-literal=tunnel-token='eyJ...' kubectl -n mcp-tunnel create secret generic mcp-tunnel-cert \ --from-file=tls.crt=data/tls.crt \ --from-file=tls.key=data/tls.key ``` ```bash helm show values \ oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \ --version 2.1.0 > values.yaml ``` Edita `values.yaml` y establece las siguientes claves: ```yaml values.yaml setup: enabled: false external: tunnelTokenSecretName: mcp-tunnel-token # must contain key: tunnel-token serverCertSecretName: mcp-tunnel-cert # must contain keys: tls.crt, tls.key gateway: config: # Required when setup.enabled is false. Replace the placeholder with # the $TUNNEL_DOMAIN value you exported earlier. When setup.enabled # is true the chart injects this from the Secret as a -tunnel-domain # flag instead. tunnel_domain: YOUR_TUNNEL_DOMAIN_HERE routes: docs: http://docs-mcp.internal:8080 search: http://search-mcp.internal:8080 ``` Algunas distribuciones administradas de Kubernetes asignan el CIDR de Service fuera de los rangos privados estándar; si tus rutas apuntan a Services dentro del clúster, agrega aquí `gateway.config.upstream.allowed_ips` como se describe en [Validación de IP upstream](https://platform.claude.com/docs/es/agents-and-tools/mcp-tunnels/troubleshooting#upstream-ip-validation). Si estás usando el [servidor MCP de ejemplo](https://platform.claude.com/docs/es/agents-and-tools/mcp-tunnels/deploy-helm#optional-use-a-sample-mcp-server), establece `routes` como `echo: http://hello-mcp:9000` en su lugar. ```bash helm template mcp-tunnel \ oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \ --version 2.1.0 \ -n mcp-tunnel \ -f values.yaml > rendered.yaml ``` ```bash helm install mcp-tunnel \ oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \ --version 2.1.0 \ --namespace mcp-tunnel --create-namespace \ -f values.yaml ``` ## Verifica la implementación Verifica de extremo a extremo desde el lado de Anthropic: usa `https://./` en una sesión de Managed Agent o en una solicitud a la API de Messages, donde `` es una clave de `gateway.config.routes` y `` es la ruta en la que sirve el servidor MCP upstream. Con el [servidor MCP de ejemplo](https://platform.claude.com/docs/es/agents-and-tools/mcp-tunnels/deploy-helm#optional-use-a-sample-mcp-server), eso es `https://echo./mcp`. Consulta [Usar los servidores MCP tunelizados](https://platform.claude.com/docs/es/agents-and-tools/mcp-tunnels/overview#use-the-tunneled-mcp-servers) para ver la forma 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](https://platform.claude.com/docs/es/agents-and-tools/mcp-tunnels/troubleshooting). ## 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 además 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 de cloudflared hacia el borde del túnel se permite por separado mediante `networkPolicy.egress.cloudflaredEgressCIDRs`. ### Ajusta el proxy Los campos bajo `gateway.config.*` se transfieren 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](https://platform.claude.com/docs/es/agents-and-tools/mcp-tunnels/reference#proxy-configuration) 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](https://platform.claude.com/docs/es/manage-claude/wif-providers/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 obtener un chart más reciente de forma inesperada. ### 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 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. ### Cambia la configuración Para cambios rutinarios como rutas, número de réplicas o NetworkPolicy: ```bash helm upgrade mcp-tunnel \ oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \ --version 2.1.0 \ -n mcp-tunnel \ -f values.yaml ``` Mantén un `values.yaml` completo en lugar de depender de `--reuse-values`. El comportamiento de fusión profunda de Helm puede fallar silenciosamente al eliminar rutas borradas. ### 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 las actualizaciones cuando se fuerza: ```bash helm upgrade mcp-tunnel \ oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \ --version 2.1.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 y luego actualiza el Secret `mcp-tunnel-token`: ```bash 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 ``` Hacer clic en **Rotate token** invalida el token actual de inmediato. Hasta que el Secret se actualice y el despliegue se complete, cualquier pod que se reinicie con el token anterior (desalojo, drenado de nodo, OOM) no podrá reconectarse. Actualiza el Secret rápidamente después de rotar; para requisitos de disponibilidad más estrictos, usa el acceso programático para que el chart gestione la rotación de forma atómica. ### Renovación de certificados El chart proporciona automatización, pero sigues siendo responsable de supervisar el vencimiento y confirmar que la renovación se complete. Con acceso programático, la renovación de certificados es automática. El chart implementa un CronJob (nombrado según el `fullname` de Helm, con el sufijo `-cert-renew`) que ejecuta `setup renew-cert` diariamente (en `serverCert.cronSchedule`, por defecto `0 0 * * *` UTC). El job no hace nada a menos que el certificado esté dentro de `serverCert.renewBefore` de su vencimiento (por defecto 30 días). La renovación es local: el job firma un nuevo certificado 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 es necesario 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): ```bash 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 Conecta un servidor MCP upstream a un Managed Agent o a la API de Messages. Guía de endurecimiento, rotación de credenciales y respuesta ante brechas. Diagnostica problemas de conectividad, TLS y enrutamiento.