--- title: Desplegar túneles MCP con Helm url: https://platform.claude.com/docs/es/agents-and-tools/mcp-tunnels/deploy-helm description: Instala la pila del túnel 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 del túnel](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 [Console](https://platform.claude.com/docs/es/agents-and-tools/mcp-tunnels/console#create-a-tunnel). ## 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](https://platform.claude.com/docs/es/agents-and-tools/mcp-tunnels/console#create-a-tunnel) y registra 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](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. Necesitarás una regla de federación con 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 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](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 bajo `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 servidor 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. ## Instalar El componente de configuración intercambia el token proyectado del 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 bajo su propio ServiceAccount en el namespace del 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 el 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 bien 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 un ServiceAccount separado (también derivado 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 cubrirlo. ```bash helm show values \ oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \ --version 2.0.2 > 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 alcanza los servidores en `docs.` y `search.`. Algunas distribuciones administradas de Kubernetes asignan el CIDR de Services fuera de los rangos privados estándar; si tus rutas apuntan a Services dentro del clúster, agrega `gateway.config.upstream.allowed_ips` aquí según [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 de acuerdo con 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.0.2 \ -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.0.2 \ --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 se completa. 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 [rotación del token](https://platform.claude.com/docs/es/agents-and-tools/mcp-tunnels/deploy-helm#rotate-the-tunnel-token)) reutiliza el ID de 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 es un riesgo. Los datos sensibles en reposo son el Secret `mcp-tunnel` que crea el componente de configuración, el cual contiene el token del túnel y las claves privadas TLS. Aplica las prácticas estándar de tu organización para proteger Secrets de Kubernetes a este namespace. 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 de renovación de certificados. Usa esta vía 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). Registra el dominio del túnel desde la página de detalle. 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 `*.` según 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 es solo para OpenSSL 3.0+) mantiene esto funcionando 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 de namespace no tiene efecto 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.0.2 > 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 Services fuera de los rangos privados estándar; si tus rutas apuntan a Services dentro del clúster, agrega `gateway.config.upstream.allowed_ips` aquí según [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.0.2 \ -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.0.2 \ --namespace mcp-tunnel --create-namespace \ -f values.yaml ``` ## Verifica el despliegue 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), es `https://echo./mcp`. Consulta [Usa los servidores MCP tunelizados](https://platform.claude.com/docs/es/agents-and-tools/mcp-tunnels/overview#use-the-tunneled-mcp-servers) 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](https://platform.claude.com/docs/es/agents-and-tools/mcp-tunnels/troubleshooting). ## Configuración opcional ### Restringe el tráfico saliente con NetworkPolicy El tráfico entrante al pod del proxy se deniega 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 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](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 inesperadamente un chart más reciente. ### 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 de túnel ya almacenado en el Secret `mcp-tunnel` al volver a ejecutarse), pero el movimiento explícito mantiene tu `values.yaml` preciso. Actualiza también 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.0.2 \ -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 actualizaciones cuando se fuerza: ```bash 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 detalle 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 rollout se complete, cualquier pod que se reinicie con el token antiguo (desalojo, drenado de nodo, OOM) no podrá reconectarse. Actualiza el Secret sin demora después de rotar; para requisitos de disponibilidad más estrictos, usa el acceso programático para que el chart maneje la rotación de forma atómica. ### Renovación de certificados El chart proporciona automatización, pero sigues siendo responsable de monitorear el vencimiento 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 vencimiento (predeterminado 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 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): ```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.