MessagesMCP tunnels

MCP tunnels reference

Copy page



Proxy configuration fields, the Tunnels REST API, certificate requirements, and the setup component.

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.

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 <route>.<tunnel-domain>. A wildcard *.<tunnel-domain> 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 <subcommand> (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 ANTHROPIC_FEDERATION_RULE_ID, ANTHROPIC_ORGANIZATION_ID, ANTHROPIC_WORKSPACE_ID (optional), and exactly one of ANTHROPIC_IDENTITY_TOKEN_FILE or ANTHROPIC_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 ANTHROPIC_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.