Note: MCP tunnels are in research preview. Request access to try them.

#Proxy configuration

The proxy reads its configuration from /etc/mcp-gateway/config.yaml (Compose) or the rendered ConfigMap (Helm, populated from gateway.config.*).

For https:// upstream routes, set at least one of upstream.tls.ca_file or upstream.tls.include_system_cas; otherwise the proxy has no trust anchor for the upstream certificate.

#Route matching

routes is a flat string map (map[string]string), not a list. The proxy looks up the incoming hostname by exact match first, then by stripping the tunnel_domain suffix and matching the remaining subdomain. The match considers only the hostname; the request path and query string are forwarded to the upstream MCP server unchanged.

Each upstream value must be exactly scheme://host:port. The port is mandatory. Including a path is rejected at config load with invalid upstream (must be scheme://host:port).

#Tunnels API

The Tunnels REST API lives at /v1/tunnels and supports creating, listing, and archiving tunnels, registering CA certificates, and revealing or rotating the tunnel token. See the Tunnels API reference for all endpoints, request and response schemas, and examples.

Note: The previous Admin API surface at /v1/organizations/tunnels (beta header mcp-tunnels-2026-05-19, scope org:manage_tunnels) continues to work during a migration window and remains documented in the Admin API reference with a deprecation notice. To migrate, update the path to /v1/tunnels, the beta header to mcp-tunnels-2026-06-22, and your WIF token scope to workspace:manage_tunnels.

Warning: All MCP tunnels endpoints require a bearer token with the workspace:manage_tunnels scope obtained through Workload Identity Federation. Admin API keys are not accepted.

Required headers on every request:

#Certificate requirements

The setup component generates compliant certificates automatically. These requirements apply only if you issue certificates through your own PKI.

#CA certificate

Upload with POST /v1/tunnels/{tunnel_id}/certificates. A tunnel can hold up to two active CA certificates at a time, which allows zero-downtime rotation.

• PEM-encoded, single certificate, up to 8 kB.

• BasicConstraints extension present with CA:TRUE, marked critical.

• SubjectKeyIdentifier extension present.

• KeyUsage includes keyCertSign.

• Within its validity period.

• RSA 2048-bit or larger, or ECDSA P-256 or larger, with a SHA-256 or stronger signature.

#Server certificate

Presented by the proxy during inner TLS.

• Signed directly by a registered CA (no intermediates).

• AuthorityKeyIdentifier extension present and matching the CA's SubjectKeyIdentifier.

• Subject Alternative Name includes a DNS name matching .. A wildcard *. covers all routes.

• If the ExtendedKeyUsage extension is present, it includes serverAuth.

• Within its validity period.

• RSA 2048-bit or larger, or ECDSA P-256 or larger, with a SHA-256 or stronger signature.

The setup component generates an ECDSA P-256 CA with five-year validity and an RSA 4096-bit server certificate with a wildcard SAN and 90-day validity.

#Setup component

The setup component ships inside the mcp-proxy image as the setup binary. Run it with docker compose run --rm setup (Compose) or rely on the chart's hooks and CronJobs (Helm).

#setup init

Attaches to an existing tunnel (or creates one when no tunnel ID is supplied), then generates a CA and server certificate, registers the CA, retrieves the tunnel token, and writes all outputs to the destination.

The command authenticates through Workload Identity Federation. It reads JUGLOW_FEDERATION_RULE_ID, JUGLOW_ORGANIZATION_ID, JUGLOW_WORKSPACE_ID (optional), and exactly one of JUGLOW_IDENTITY_TOKEN_FILE or JUGLOW_IDENTITY_TOKEN. See the WIF reference for the current semantics of these variables; the setup component derives the service account from the federation rule, so it does not require JUGLOW_SERVICE_ACCOUNT_ID separately.

#setup renew-cert

Issues a new server certificate signed by the stored CA. Makes no API calls.

Setting --renew-before=720h makes the command a no-op when more than 30 days of validity remain, so it's safe to run on a fixed schedule.