--- title: Referencia de túneles MCP url: https://platform.claude.com/docs/es/agents-and-tools/mcp-tunnels/reference description: Campos de configuración del proxy, la API REST de Tunnels, requisitos de certificados y el componente de configuración. --- 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. ## Configuración del proxy El [proxy](https://platform.claude.com/docs/es/agents-and-tools/mcp-tunnels/concepts#components) lee su configuración desde `/etc/mcp-gateway/config.yaml` (Compose) o desde el ConfigMap renderizado (Helm, poblado a partir de `gateway.config.*`). | Campo | Descripción | Valor predeterminado | | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- | | `listen_addr` | Dirección y puerto en los que escuchar. | Obligatorio | | `log_level` | Nivel de detalle del registro: `debug`, `info`, `warn` o `error`. | `info` | | `shutdown_timeout` | Cuánto tiempo esperar a las solicitudes en curso durante un apagado ordenado. | `30s` | | `tunnel_domain` | Dominio base asignado al túnel. Cuando se establece, la búsqueda de rutas elimina este sufijo de los nombres de host entrantes para que las claves de `routes` puedan ser subdominios simples (`wiki`). Cuando está vacío, las claves de `routes` deben ser nombres de host completos exactos. | Obligatorio cuando las claves de `routes` son subdominios simples | | `tls.cert_file` | Ruta al certificado TLS del servidor. | Obligatorio | | `tls.key_file` | Ruta a la clave privada TLS del servidor. | Obligatorio | | `routes` | Mapa de subdominio o nombre de host completo a URL upstream. Consulta [Coincidencia de rutas](https://platform.claude.com/docs/es/agents-and-tools/mcp-tunnels/reference#route-matching). | Obligatorio | | `upstream.allowed_ips` | Rangos CIDR IPv4 o direcciones individuales a las que el proxy tiene permitido conectarse. Mutuamente excluyente con `disable_ip_validation`. | Rangos privados RFC1918 | | `upstream.disable_ip_validation` | Deshabilita por completo la validación de IP upstream. Mutuamente excluyente con `allowed_ips`. | `false` | | `upstream.tls.ca_file` | Paquete de CA para validar el TLS upstream. | Ninguno | | `upstream.tls.include_system_cas` | Confiar también en el paquete de CA del sistema para el TLS upstream. | `false` | Para rutas upstream `https://`, establece al menos uno de `upstream.tls.ca_file` o `upstream.tls.include_system_cas`; de lo contrario, el proxy no tiene un ancla de confianza para el certificado upstream. ### Coincidencia de rutas `routes` es un mapa plano de cadenas (`map[string]string`), no una lista. El proxy busca el nombre de host entrante primero por coincidencia exacta y luego eliminando el sufijo `tunnel_domain` y haciendo coincidir el subdominio restante. La coincidencia considera únicamente el nombre de host; la ruta de la solicitud y la cadena de consulta se reenvían sin cambios al [servidor MCP upstream](https://platform.claude.com/docs/es/agents-and-tools/mcp-tunnels/concepts#components). Cada valor upstream debe ser exactamente `scheme://host:port`. El puerto es obligatorio. Incluir una ruta se rechaza al cargar la configuración con `invalid upstream (must be scheme://host:port)`. ## API de Tunnels La API REST de Tunnels se encuentra en `/v1/tunnels` y permite crear, listar y archivar túneles, registrar certificados de CA y revelar o rotar el token del túnel. Consulta la [referencia de la API de Tunnels](https://platform.claude.com/docs/es/api/beta/tunnels/list) para ver todos los endpoints, los esquemas de solicitud y respuesta, y ejemplos. La superficie anterior de la Admin API en `/v1/organizations/tunnels` (encabezado beta `mcp-tunnels-2026-05-19`, alcance `org:manage_tunnels`) sigue funcionando durante una ventana de migración y permanece documentada en la [referencia de la Admin API](https://platform.claude.com/docs/es/api/beta/organization/mcp_tunnels) con un aviso de obsolescencia. Para migrar, actualiza la ruta a `/v1/tunnels`, el encabezado beta a `mcp-tunnels-2026-06-22` y el alcance de tu token WIF a `workspace:manage_tunnels`. Todos los endpoints de túneles MCP requieren un token bearer con el alcance `workspace:manage_tunnels` obtenido mediante [Workload Identity Federation](https://platform.claude.com/docs/es/manage-claude/workload-identity-federation). No se aceptan claves de la Admin API. Encabezados obligatorios en cada solicitud: | Encabezado | Valor | | ------------------- | ------------------------------------------------------ | | `Authorization` | `Bearer ` (el token intercambiado mediante WIF) | | `anthropic-version` | `2023-06-01` | | `anthropic-beta` | `mcp-tunnels-2026-06-22` | ## Requisitos de certificados El [componente de configuración](https://platform.claude.com/docs/es/agents-and-tools/mcp-tunnels/concepts#components) genera automáticamente certificados que cumplen los requisitos. Estos requisitos aplican únicamente si emites certificados a través de tu propia PKI. ### Certificado de CA Súbelo con `POST /v1/tunnels/{tunnel_id}/certificates`. Un túnel puede tener hasta dos certificados de CA activos a la vez, lo que permite una rotación sin tiempo de inactividad. * Codificado en PEM, un único certificado, de hasta 8 kB. * Extensión `BasicConstraints` presente con `CA:TRUE`, marcada como crítica. * Extensión `SubjectKeyIdentifier` presente. * `KeyUsage` incluye `keyCertSign`. * Dentro de su período de validez. * RSA de 2048 bits o mayor, o ECDSA P-256 o mayor, con una firma SHA-256 o más fuerte. ### Certificado del servidor Presentado por el proxy durante el [TLS interno](https://platform.claude.com/docs/es/agents-and-tools/mcp-tunnels/concepts#components). * Firmado directamente por una CA registrada (sin intermediarios). * Extensión `AuthorityKeyIdentifier` presente y coincidente con el `SubjectKeyIdentifier` de la CA. * El Subject Alternative Name incluye un nombre DNS que coincide con `.`. Un comodín `*.` cubre todas las rutas. * Si la extensión `ExtendedKeyUsage` está presente, incluye `serverAuth`. * Dentro de su período de validez. * RSA de 2048 bits o mayor, o ECDSA P-256 o mayor, con una firma SHA-256 o más fuerte. El componente de configuración genera una CA ECDSA P-256 con validez de cinco años y un certificado de servidor RSA de 4096 bits con un SAN comodín y validez de 90 días. ## Componente de configuración El componente de configuración se distribuye dentro de la imagen `mcp-proxy` como el binario `setup`. Ejecútalo con `docker compose run --rm setup ` (Compose) o apóyate en los hooks y CronJobs del chart (Helm). ### `setup init` Se conecta a un túnel existente (o crea uno cuando no se proporciona un ID de túnel), luego genera una CA y un certificado de servidor, registra la CA, obtiene el token del túnel y escribe todas las salidas en el destino. | Flag | Descripción | Valor predeterminado | | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | | `--api-url` | URL base de la Claude API. También se lee desde `API_URL`. | Obligatorio | | `--tunnel-id` | ID del túnel al que conectarse (`tnl_...`). También se lee desde `TUNNEL_ID`. Cuando se omite, se crea un nuevo túnel; un ID de túnel ya almacenado en la salida se reutiliza en ejecuciones posteriores. | Ninguno (crear un túnel) | | `--output` | Destino de salida: `dir:/path` o `k8s-secret:NAME`. El chart de Helm pasa `k8s-secret:`. | `k8s-secret:mcp-tunnel` (detectado automáticamente al ejecutarse en un pod de Kubernetes; obligatorio en caso contrario) | | `--cert-duration` | Período de validez del certificado del servidor. | `2160h` (90 días) | | `--token-version` | Cadena de detección de cambios. Un valor nuevo activa la rotación del token al volver a ejecutar. Tanto el chart de Helm como el ejemplo de Compose pasan `1` como valor inicial. | Ninguno | El comando se autentica mediante [Workload Identity Federation](https://platform.claude.com/docs/es/manage-claude/workload-identity-federation). Lee `ANTHROPIC_FEDERATION_RULE_ID`, `ANTHROPIC_ORGANIZATION_ID`, `ANTHROPIC_WORKSPACE_ID` (opcional) y exactamente uno de `ANTHROPIC_IDENTITY_TOKEN_FILE` o `ANTHROPIC_IDENTITY_TOKEN`. Consulta la [referencia de WIF](https://platform.claude.com/docs/es/manage-claude/wif-reference) para conocer la semántica actual de estas variables; el componente de configuración deriva la cuenta de servicio a partir de la regla de federación, por lo que no requiere `ANTHROPIC_SERVICE_ACCOUNT_ID` por separado. ### `setup renew-cert` Emite un nuevo certificado de servidor firmado por la CA almacenada. No realiza llamadas a la API. | Flag | Descripción | Valor predeterminado | | ----------------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | | `--output` | Destino de salida: `dir:/path` o `k8s-secret:NAME`. El chart de Helm pasa `k8s-secret:`. | `k8s-secret:mcp-tunnel` (detectado automáticamente al ejecutarse en un pod de Kubernetes; obligatorio en caso contrario) | | `--cert-duration` | Período de validez del nuevo certificado. | `2160h` (90 días) | | `--renew-before` | Omite la renovación si al certificado existente le queda más de esta duración. | `0` (renovar siempre) | Establecer `--renew-before=720h` hace que el comando no realice ninguna acción cuando quedan más de 30 días de validez, por lo que es seguro ejecutarlo con una programación fija.