Repository Public
1---2title: MCP tunnels reference3url: https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/reference4description: Proxy configuration fields, the Tunnels REST API, certificate requirements, and the setup component.5---67<Note>8 MCP tunnels are in research preview. [Request access](https://claude.com/form/mcp-tunnels) to try them.9</Note>1011## Proxy configuration1213The [proxy](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/concepts#components) reads its configuration from `/etc/mcp-gateway/config.yaml` (Compose) or the rendered ConfigMap (Helm, populated from `gateway.config.*`).1415| Field | Description | Default |16| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- |17| `listen_addr` | Address and port to listen on. | Required |18| `log_level` | Logging verbosity: `debug`, `info`, `warn`, or `error`. | `info` |19| `shutdown_timeout` | How long to wait for in-flight requests during graceful shutdown. | `30s` |20| `tunnel_domain` | Base domain assigned to the tunnel. When set, route lookup strips this suffix from incoming hostnames so `routes` keys can be bare subdomains (`wiki`). When empty, `routes` keys must be exact full hostnames. | Required when `routes` keys are bare subdomains |21| `tls.cert_file` | Path to the server TLS certificate. | Required |22| `tls.key_file` | Path to the server TLS private key. | Required |23| `routes` | Map of subdomain or full hostname to upstream URL. See [Route matching](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/reference#route-matching). | Required |24| `upstream.allowed_ips` | IPv4 CIDR ranges or single addresses the proxy is permitted to connect to. Mutually exclusive with `disable_ip_validation`. | RFC1918 private ranges |25| `upstream.disable_ip_validation` | Disable upstream IP validation entirely. Mutually exclusive with `allowed_ips`. | `false` |26| `upstream.tls.ca_file` | CA bundle for validating upstream TLS. | None |27| `upstream.tls.include_system_cas` | Also trust the system CA bundle for upstream TLS. | `false` |2829For `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.3031### Route matching3233`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](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/concepts#components) unchanged.3435Each 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)`.3637## Tunnels API3839The 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](https://platform.claude.com/docs/en/api/beta/tunnels/list) for all endpoints, request and response schemas, and examples.4041<Note>42 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](https://platform.claude.com/docs/en/api/admin/mcp_tunnels) 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`.43</Note>4445<Warning>46 All MCP tunnels endpoints require a bearer token with the `workspace:manage_tunnels` scope obtained through [Workload Identity Federation](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation). Admin API keys are not accepted.47</Warning>4849Required headers on every request:5051| Header | Value |52| ------------------- | ------------------------------------------ |53| `Authorization` | `Bearer <token>` (the WIF-exchanged token) |54| `anthropic-version` | `2023-06-01` |55| `anthropic-beta` | `mcp-tunnels-2026-06-22` |5657## Certificate requirements5859The [setup component](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/concepts#components) generates compliant certificates automatically. These requirements apply only if you issue certificates through your own PKI.6061### CA certificate6263Upload 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.6465* PEM-encoded, single certificate, up to 8 kB.66* `BasicConstraints` extension present with `CA:TRUE`, marked critical.67* `SubjectKeyIdentifier` extension present.68* `KeyUsage` includes `keyCertSign`.69* Within its validity period.70* RSA 2048-bit or larger, or ECDSA P-256 or larger, with a SHA-256 or stronger signature.7172### Server certificate7374Presented by the proxy during [inner TLS](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/concepts#components).7576* Signed directly by a registered CA (no intermediates).77* `AuthorityKeyIdentifier` extension present and matching the CA's `SubjectKeyIdentifier`.78* Subject Alternative Name includes a DNS name matching `<route>.<tunnel-domain>`. A wildcard `*.<tunnel-domain>` covers all routes.79* If the `ExtendedKeyUsage` extension is present, it includes `serverAuth`.80* Within its validity period.81* RSA 2048-bit or larger, or ECDSA P-256 or larger, with a SHA-256 or stronger signature.8283The 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.8485## Setup component8687The 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).8889### `setup init`9091Attaches 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.9293| Flag | Description | Default |94| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |95| `--api-url` | Claude API base URL. Also read from `API_URL`. | Required |96| `--tunnel-id` | Tunnel ID to attach to (`tnl_...`). Also read from `TUNNEL_ID`. When omitted, a new tunnel is created; a tunnel ID already stored in the output is reused on re-runs. | None (create a tunnel) |97| `--output` | Output destination: `dir:/path` or `k8s-secret:NAME`. The Helm chart passes `k8s-secret:<release>`. | `k8s-secret:mcp-tunnel` (auto-detected when running in a Kubernetes pod; required otherwise) |98| `--cert-duration` | Server certificate validity period. | `2160h` (90 days) |99| `--token-version` | Change-detection string. A new value triggers token rotation on re-run. The Helm chart and the Compose example both pass `1` as the initial value. | None |100101The command authenticates through [Workload Identity Federation](https://platform.claude.com/docs/en/manage-claude/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](https://platform.claude.com/docs/en/manage-claude/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.102103### `setup renew-cert`104105Issues a new server certificate signed by the stored CA. Makes no API calls.106107| Flag | Description | Default |108| ----------------- | --------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |109| `--output` | Output destination: `dir:/path` or `k8s-secret:NAME`. The Helm chart passes `k8s-secret:<release>`. | `k8s-secret:mcp-tunnel` (auto-detected when running in a Kubernetes pod; required otherwise) |110| `--cert-duration` | New certificate validity period. | `2160h` (90 days) |111| `--renew-before` | Skip renewal if the existing certificate has more than this duration remaining. | `0` (always renew) |112113Setting `--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.114