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 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 de 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 al servidor MCP de upstream sin cambios.

Cada valor de upstream debe ser exactamente scheme://host:port. El puerto es obligatorio. Incluir una ruta se rechaza al cargar la configuración con el mensaje invalid upstream (must be scheme://host:port).

API de Tunnels

Consulta la referencia de la API de administración de túneles MCP para ver todos los endpoints, esquemas de solicitud y respuesta, y ejemplos por lenguaje.

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/organizations/tunnels/{tunnel_id}/certificates. Un túnel puede contener hasta dos certificados de CA activos a la vez, lo que permite la 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 de 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 al túnel que creaste en la Console, 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.