Referencia de túneles MCP



Configuración del proxy

El proxy lee su configuración desde /etc/mcp-gateway/config.yaml (Compose) o desde el ConfigMap renderizado (Helm, poblado a partir de gateway.config.*).

Para rutas de destino 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 de destino.



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, 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 de destino.

Cada valor de destino 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 para ver todos los endpoints, esquemas de solicitud y respuesta, y ejemplos.

Encabezados obligatorios en cada solicitud:



Requisitos de certificados

El componente de configuración genera automáticamente certificados que cumplen con los requisitos. Estos requisitos aplican únicamente si emites certificados a través de tu propia PKI.



Certificado de CA

Se carga con POST /v1/tunnels/{tunnel_id}/certificates. Un túnel puede contener hasta dos certificados de CA activos a la vez, lo que permite una rotación sin tiempo de inactividad.

• Codificado en PEM, un solo certificado, 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 superior, o ECDSA P-256 o superior, con una firma SHA-256 o más fuerte.



Certificado del servidor

Presentado por el proxy durante el TLS interno.

• 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 <route>.<tunnel-domain>. Un comodín *.<tunnel-domain> 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 superior, o ECDSA P-256 o superior, 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 incluye dentro de la imagen mcp-proxy como el binario setup. Ejecútalo con docker compose run --rm setup <subcommand> (Compose) o utiliza 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, recupera el token del túnel y escribe todas las salidas en el destino.

El comando se autentica a través de 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 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.

Establecer --renew-before=720h hace que el comando no realice ninguna operación cuando quedan más de 30 días de validez, por lo que es seguro ejecutarlo en un horario fijo.