SPB Git

Repository Public

deploy-helm.md 23.8 KB 438 lines markdown

1---2title: Deploy MCP tunnels with Helm3url: https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/deploy-helm4description: Install the tunnel stack on a Kubernetes cluster using the Anthropic Helm chart.5---67<Note>8  MCP tunnels are in research preview. [Request access](https://claude.com/form/mcp-tunnels) to try them.9</Note>1011The Anthropic Helm chart installs the [tunnel stack](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/concepts#components) as a single Deployment and attaches it to your tunnel: one the chart's setup hook creates for you, or an existing tunnel you created in the [Console](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/console#create-a-tunnel).1213## Before you begin1415You need:1617* **A tunnel.** With programmatic access, the chart's setup hook creates one for you when you don't supply a tunnel ID; to attach to an existing tunnel instead, [create it in the Console](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/console#create-a-tunnel) and record the tunnel ID (`tnl_...`). Manual provisioning always starts from a Console-created tunnel; you'll also need its tunnel token and tunnel domain.1819* **A way for the chart to authenticate to the Tunnels API.**2021  * **[Programmatic access](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/concepts#credential-provisioning) (recommended).** The [setup component](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/concepts#components) authenticates through Workload Identity Federation, fetches the tunnel token, generates a CA, registers it with Anthropic, and stores everything in a Secret. You'll need a federation rule scoped to `workspace:manage_tunnels`.22  * **[Manual](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/concepts#credential-provisioning).** Skip programmatic access. You'll [get the tunnel token from the Console](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/console#get-the-connection-details), generate a CA and server certificate yourself, [register the CA in the Console](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/console#add-a-ca-certificate), and supply the credentials to the cluster as Secrets.2324* **A Kubernetes cluster** you can deploy to with `helm` and `kubectl`. The **Without programmatic access** tab also uses `openssl` (1.1.1 or later).2526* **Outbound network connectivity** from the cluster to `api.anthropic.com` (443 TCP) and the [tunnel edge](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/concepts#components) (7844 TCP and UDP). See the full [network requirements](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/overview#network-requirements).2728* **One or more MCP servers** running and reachable from the cluster on the addresses you'll configure under `gateway.config.routes`. If you don't have one yet, [use the sample server](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/deploy-helm#optional-use-a-sample-mcp-server).2930## Optional: Use a sample MCP server3132If you don't have an MCP server available for testing, use this minimal one:3334```bash35kubectl create namespace mcp-tunnel --dry-run=client -o yaml | kubectl apply -f -36kubectl -n mcp-tunnel apply -f - <<'EOF'37apiVersion: v138kind: ConfigMap39metadata:40  name: hello-mcp-src41data:42  hello_server.py: |43    from mcp.server.fastmcp import FastMCP4445    mcp = FastMCP("hello-server", host="0.0.0.0", port=9000)464748    @mcp.tool()49    def hello(name: str = "world") -> str:50        """Say hello to someone."""51        return f"Hello, {name}!"525354    if __name__ == "__main__":55        mcp.run(transport="streamable-http")56---57apiVersion: apps/v158kind: Deployment59metadata:60  name: hello-mcp61spec:62  replicas: 163  selector:64    matchLabels: { app: hello-mcp }65  template:66    metadata:67      labels: { app: hello-mcp }68    spec:69      containers:70        - name: hello-mcp71          image: python:3.13-slim72          command: ["sh", "-c", "pip install --quiet mcp && python /app/hello_server.py"]73          volumeMounts:74            - { name: src, mountPath: /app }75          ports:76            - { containerPort: 9000 }77      volumes:78        - name: src79          configMap: { name: hello-mcp-src }80---81apiVersion: v182kind: Service83metadata:84  name: hello-mcp85spec:86  selector: { app: hello-mcp }87  ports:88    - { port: 9000, targetPort: 9000 }89EOF90```9192The Install steps that follow note where to add the corresponding route.9394## Install9596<Tabs>97  <Tab title="With programmatic access">98    The setup component exchanges the cluster's projected ServiceAccount token through your federation rule, fetches the tunnel token, generates a CA and server certificate, and registers the CA with Anthropic. A daily CronJob renews the server certificate as needed, so you don't handle any secrets by hand.99100    <Steps>101      <Step title="Set up Workload Identity Federation for the cluster">102        Follow [Use WIF with Kubernetes](https://platform.claude.com/docs/en/manage-claude/wif-providers/kubernetes) to register your cluster's OIDC issuer and create a federation rule. The setup component runs under its own ServiceAccount in the release namespace; the exact name follows Helm's `fullname` convention, so for any release name other than `mcp-tunnel`, run `helm template <release> ... | grep -A2 'kind: ServiceAccount'` to confirm it before creating the rule. The rest of this guide assumes release name `mcp-tunnel` in namespace `mcp-tunnel`, where the ServiceAccount is `mcp-tunnel-setup`.103104        | Field    | Value                                                |105        | -------- | ---------------------------------------------------- |106        | Subject  | `system:serviceaccount:mcp-tunnel:mcp-tunnel-setup`  |107        | Audience | `api.anthropic.com` (the chart's default; no scheme) |108        | Scope    | `workspace:manage_tunnels`                           |109110        <Note>111          The chart's default audience is `api.anthropic.com` with no scheme, but the Console's federation-rule form suggests `https://api.anthropic.com`. The two must match byte-for-byte or authentication fails. Either set the rule's audience to `api.anthropic.com`, or set `api.wif.audience` in `values.yaml` to `https://api.anthropic.com`.112        </Note>113114        If the tunnel is in a workspace other than the organization's default, also add the rule's service account as a member of that workspace under **Settings > Workspaces** (the Tunnels API authorizes against the service account's workspace memberships).115116        Note the rule's ID (`fdrl_...`); you'll set it as `api.wif.federationRuleId`.117118        <Note>119          The daily certificate-renewal CronJob uses a separate ServiceAccount (also derived from the Helm `fullname`) but does not call the Tunnels API; it renews the certificate locally and only needs Kubernetes RBAC, which the chart grants. The federation rule does not need to cover it.120        </Note>121      </Step>122123      <Step title="Fetch the default values">124        ```bash125        helm show values \126          oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \127          --version 2.0.2 > values.yaml128        ```129      </Step>130131      <Step title="Configure tunnel attachment and routes">132        Edit `values.yaml` and set the `api.wif.*` keys with the federation rule ID and organization ID, plus a `routes` entry for each [upstream MCP server](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/concepts#components):133134        ```yaml values.yaml135        api:136          wif:137            federationRuleId: "fdrl_..."138            organizationId: "00000000-0000-0000-0000-000000000000"139            # Set when the tunnel is in a non-default workspace and the140            # rule's service account is a member of that workspace.141            # workspaceId: "wrkspc_..."142143        tunnel:144          # Leave empty to have the setup hook create a tunnel during install.145          # Set to attach to an existing tunnel from the Console.146          id: ""147          # Increment to rotate the tunnel token on the next upgrade.148          # See the "Rotate the tunnel token" section.149          tokenVersion: "1"150151        gateway:152          config:153            routes:154              docs: http://docs-mcp.internal:8080155              search: http://search-mcp.internal:8080156        ```157158        With these routes, Claude reaches the servers at `docs.<your-tunnel-domain>` and `search.<your-tunnel-domain>`. Some managed Kubernetes distributions allocate the Service CIDR outside the standard private ranges; if your routes target in-cluster Services, add `gateway.config.upstream.allowed_ips` here per [Upstream IP validation](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/troubleshooting#upstream-ip-validation).159160        <Note>161          If you're using the [sample MCP server](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/deploy-helm#optional-use-a-sample-mcp-server), set `routes` to `echo: http://hello-mcp:9000` instead.162        </Note>163      </Step>164165      <Step title="Review the rendered manifests">166        Render the chart and review the output according to your organization's vetting practices:167168        ```bash169        helm template mcp-tunnel \170          oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \171          --version 2.0.2 \172          -n mcp-tunnel \173          -f values.yaml > rendered.yaml174        ```175      </Step>176177      <Step title="Install">178        ```bash179        helm install mcp-tunnel \180          oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \181          --version 2.0.2 \182          --namespace mcp-tunnel --create-namespace \183          -f values.yaml184        ```185186        The setup component runs as a Helm pre-install hook Job, so `helm install` blocks until it completes. On success Helm deletes the Job automatically. If `helm install` fails with a hook error, see [Setup component authentication failures](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/troubleshooting#setup-component-authentication-failures).187188        When `tunnel.id` is empty, the setup component creates the tunnel in the workspace your federation rule targets (the organization's default workspace unless you set `api.wif.workspaceId`) and stores its ID and domain in the `mcp-tunnel` Secret. Find the domain you'll need for [verification](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/deploy-helm#verify-the-deployment) on the tunnel's detail page in the Console under **Manage > MCP tunnels**, or read it from the Secret:189190        ```bash191        kubectl -n mcp-tunnel get secret mcp-tunnel \192          -o jsonpath='{.data.tunnel-domain}' | base64 -d193        ```194195        Re-running the setup component (during [upgrades](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/deploy-helm#upgrades) or [token rotation](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/deploy-helm#rotate-the-tunnel-token)) reuses the tunnel ID stored in this Secret; it never creates a second tunnel.196197        <Warning>198          The `api.wif.*` values are identifiers, not secrets, so storing them in Helm release-history Secrets is not a risk. The sensitive data at rest is the `mcp-tunnel` Secret the setup component creates, which holds the tunnel token and TLS private keys. Apply your organization's standard practices for protecting Kubernetes Secrets to this namespace.199        </Warning>200      </Step>201    </Steps>202  </Tab>203204  <Tab title="Without programmatic access">205    In this mode (`setup.enabled: false`) the chart makes no API calls; the setup component does not run and there is no cert-renew CronJob. Use this path if you'd rather not set up Workload Identity Federation.206207    <Steps>208      <Step title="Get the tunnel token and domain">209        [Create the tunnel](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/console#create-a-tunnel) and [get the tunnel token from the Console](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/console#get-the-connection-details).210211        <Note>212          Record the tunnel domain from the detail page. You'll set it as `gateway.config.tunnel_domain`.213        </Note>214      </Step>215216      <Step title="Generate a CA and server certificate">217        The proxy listens on plain WebSocket, with [inner TLS](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/concepts#components) carried inside that stream using the certificate you generate here. The server certificate's SAN must include `*.<tunnel-domain>` per the [certificate requirements](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/reference#certificate-requirements).218219        ```bash220        export TUNNEL_DOMAIN=YOUR_TUNNEL_DOMAIN_HERE221        mkdir -p mcp-tunnel/data222        cd mcp-tunnel223224        # Self-signed CA. Explicit extensions so it satisfies the certificate225        # requirements regardless of distro openssl.cnf defaults.226        openssl req -x509 -newkey rsa:2048 -nodes \227          -keyout data/ca.key -out data/ca.crt \228          -days 3650 -subj "/CN=mcp-tunnel-ca" \229          -addext "basicConstraints=critical,CA:TRUE" \230          -addext "keyUsage=critical,keyCertSign,cRLSign" \231          -addext "subjectKeyIdentifier=hash"232233        # Extension file for the server certificate. Using -extfile (instead of234        # -copy_extensions, which is OpenSSL 3.0+ only) keeps this working on235        # OpenSSL 1.1.x.236        cat > data/tls.ext <<EOF237        subjectAltName = DNS:${TUNNEL_DOMAIN},DNS:*.${TUNNEL_DOMAIN}238        authorityKeyIdentifier = keyid,issuer239        extendedKeyUsage = serverAuth240        EOF241242        # Server certificate signed by the CA243        openssl req -newkey rsa:2048 -nodes \244          -keyout data/tls.key -out /tmp/server.csr \245          -subj "/CN=${TUNNEL_DOMAIN}"246        openssl x509 -req -in /tmp/server.csr \247          -CA data/ca.crt -CAkey data/ca.key -CAcreateserial \248          -out data/tls.crt -days 90 \249          -extfile data/tls.ext250        ```251252        [Register `data/ca.crt` in the Console](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/console#add-a-ca-certificate). Keep `data/ca.key` somewhere durable and secure; you'll need it to sign a fresh server certificate at renewal time.253      </Step>254255      <Step title="Create the two Secrets">256        The chart reads specific keys; the Secret names are configurable but the keys are not. The following namespace-creation command is a no-op if the namespace already exists (for example, from the [sample MCP server](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/deploy-helm#optional-use-a-sample-mcp-server) step).257258        ```bash259        kubectl create namespace mcp-tunnel --dry-run=client -o yaml | kubectl apply -f -260        kubectl -n mcp-tunnel create secret generic mcp-tunnel-token \261          --from-literal=tunnel-token='eyJ...'262        kubectl -n mcp-tunnel create secret generic mcp-tunnel-cert \263          --from-file=tls.crt=data/tls.crt \264          --from-file=tls.key=data/tls.key265        ```266      </Step>267268      <Step title="Fetch the default values">269        ```bash270        helm show values \271          oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \272          --version 2.0.2 > values.yaml273        ```274      </Step>275276      <Step title="Configure values for manual provisioning">277        Edit `values.yaml` and set the following keys:278279        ```yaml values.yaml280        setup:281          enabled: false282283        external:284          tunnelTokenSecretName: mcp-tunnel-token   # must contain key: tunnel-token285          serverCertSecretName: mcp-tunnel-cert     # must contain keys: tls.crt, tls.key286287        gateway:288          config:289            # Required when setup.enabled is false. Replace the placeholder with290            # the $TUNNEL_DOMAIN value you exported earlier. When setup.enabled291            # is true the chart injects this from the Secret as a -tunnel-domain292            # flag instead.293            tunnel_domain: YOUR_TUNNEL_DOMAIN_HERE294            routes:295              docs: http://docs-mcp.internal:8080296              search: http://search-mcp.internal:8080297        ```298299        Some managed Kubernetes distributions allocate the Service CIDR outside the standard private ranges; if your routes target in-cluster Services, add `gateway.config.upstream.allowed_ips` here per [Upstream IP validation](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/troubleshooting#upstream-ip-validation).300301        <Note>302          If you're using the [sample MCP server](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/deploy-helm#optional-use-a-sample-mcp-server), set `routes` to `echo: http://hello-mcp:9000` instead.303        </Note>304      </Step>305306      <Step title="Review the rendered manifests">307        ```bash308        helm template mcp-tunnel \309          oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \310          --version 2.0.2 \311          -n mcp-tunnel \312          -f values.yaml > rendered.yaml313        ```314      </Step>315316      <Step title="Install">317        ```bash318        helm install mcp-tunnel \319          oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \320          --version 2.0.2 \321          --namespace mcp-tunnel --create-namespace \322          -f values.yaml323        ```324      </Step>325    </Steps>326  </Tab>327</Tabs>328329## Verify the deployment330331Verify end to end from Anthropic's side: use `https://<route>.<your-tunnel-domain>/<path>` in a Managed Agent session or a Messages API request, where `<route>` is a key from `gateway.config.routes` and `<path>` is whatever the upstream MCP server serves at. With the [sample MCP server](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/deploy-helm#optional-use-a-sample-mcp-server), that's `https://echo.<your-tunnel-domain>/mcp`. See [Use the tunneled MCP servers](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/overview#use-the-tunneled-mcp-servers) for the request shapes.332333If that fails, check the pod logs (`kubectl -n mcp-tunnel logs deploy/mcp-tunnel -c mcp-proxy` and `-c cloudflared`) and consult [Troubleshooting](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/troubleshooting).334335## Optional configuration336337### Restrict egress with NetworkPolicy338339Ingress to the proxy pod is denied by default (`networkPolicy.ingress.enabled: true`). To additionally restrict pod egress, set `networkPolicy.egress.enabled: true` and populate `networkPolicy.egress.mcpServers` with pod label selectors or CIDR ranges that cover your upstream MCP servers. Egress from cloudflared to the tunnel edge is allowed separately through `networkPolicy.egress.cloudflaredEgressCIDRs`.340341### Tune the proxy342343Fields under `gateway.config.*` pass through to the proxy configuration file. Common adjustments include `upstream.allowed_ips`, `log_level`, and `upstream.tls`. See the [proxy configuration](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/reference#proxy-configuration) reference for the full field list. The chart always sets `listen_addr`, `tls.cert_file`, and `tls.key_file`; setting them in `gateway.config` has no effect.344345### Supply your own OIDC token346347By default the chart projects a Kubernetes ServiceAccount token for the setup component. To use a token from a different identity provider (such as [SPIFFE](https://platform.claude.com/docs/en/manage-claude/wif-providers/spiffe), Vault, or a cloud-SDK sidecar), mount it with `setup.extraVolumes` and `setup.extraVolumeMounts`. Then point `api.wif.tokenFile` at the mount path. The chart sets `ANTHROPIC_IDENTITY_TOKEN_FILE` to that path, and the setup component reads the token from there.348349## Upgrades350351Always pass `--version` to `helm upgrade` so you don't pull a newer chart unexpectedly.352353### Upgrade from chart 1.x354355Chart 2.0.0 moves the tunnel ID from `api.wif.tunnelId` to `tunnel.id`. Before upgrading, edit your `values.yaml`: move the `tnl_...` value to `tunnel.id` and remove `api.wif.tunnelId`. Leaving `tunnel.id` unset is safe (the setup component reuses the tunnel ID already stored in the `mcp-tunnel` Secret on re-run), but the explicit move keeps your `values.yaml` accurate. Also update your federation rule's scope from `org:manage_tunnels` to `workspace:manage_tunnels` in the Console.356357### Change configuration358359For routine changes such as routes, replica count, or NetworkPolicy:360361```bash362helm upgrade mcp-tunnel \363  oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \364  --version 2.0.2 \365  -n mcp-tunnel \366  -f values.yaml367```368369<Warning>370  Maintain a complete `values.yaml` rather than relying on `--reuse-values`. Helm's deep-merge behavior can silently fail to remove deleted routes.371</Warning>372373### Rotate the tunnel token374375With programmatic access, increment `tunnel.tokenVersion` in `values.yaml` and upgrade with `--set setup.force=true`. The setup component only re-runs on upgrades when forced:376377```bash378helm upgrade mcp-tunnel \379  oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \380  --version 2.0.2 \381  -n mcp-tunnel \382  -f values.yaml \383  --set setup.force=true384```385386The setup component authenticates with Workload Identity Federation; there is no API token to revoke.387388Without programmatic access, click **Rotate token** on the tunnel detail page in the Console, then update the `mcp-tunnel-token` Secret:389390```bash391kubectl -n mcp-tunnel create secret generic mcp-tunnel-token \392  --from-literal=tunnel-token='eyJ...' --dry-run=client -o yaml | kubectl apply -f -393kubectl -n mcp-tunnel rollout restart deploy/mcp-tunnel394```395396<Warning>397  Clicking **Rotate token** invalidates the current token immediately. Until the Secret is updated and the rollout completes, any pod that restarts with the old token (eviction, node drain, OOM) cannot reconnect. Update the Secret promptly after rotating; for stricter availability requirements, use programmatic access so the chart handles the rotation atomically.398</Warning>399400### Certificate renewal401402The chart provides automation, but you remain responsible for monitoring expiry and confirming renewal completes.403404With programmatic access, certificate renewal is automatic. The chart deploys a CronJob (named after the Helm `fullname`, suffixed `-cert-renew`) that runs `setup renew-cert` daily (at `serverCert.cronSchedule`, default `0 0 * * *` UTC). The job is a no-op unless the certificate is within `serverCert.renewBefore` of expiry (default 30 days). Renewal is local: the job signs a fresh certificate with the CA already stored in the Secret, makes no API calls, and only needs the Kubernetes RBAC the chart grants. The proxy hot-reloads the certificate from the Secret mount, so no Deployment restart is needed.405406Without programmatic access there is no CronJob. From inside the `mcp-tunnel/` directory you kept after install, sign a fresh server certificate with the existing CA (do not regenerate the CA):407408```bash409export TUNNEL_DOMAIN=YOUR_TUNNEL_DOMAIN_HERE410openssl req -new -key data/tls.key -out /tmp/server.csr \411  -subj "/CN=${TUNNEL_DOMAIN}"412openssl x509 -req -in /tmp/server.csr \413  -CA data/ca.crt -CAkey data/ca.key -CAcreateserial \414  -out data/tls.crt -days 90 -extfile data/tls.ext415416kubectl -n mcp-tunnel create secret generic mcp-tunnel-cert \417  --from-file=tls.crt=data/tls.crt --from-file=tls.key=data/tls.key \418  --dry-run=client -o yaml | kubectl apply -f -419```420421The proxy hot-reloads the certificate from the Secret mount.422423## Next steps424425<CardGroup cols={2}>426  <Card title="Use the tunneled MCP servers" icon="link" href="https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/overview#use-the-tunneled-mcp-servers">427    Attach an upstream MCP server to a Managed Agent or the Messages API.428  </Card>429430  <Card title="Security" icon="lock" href="https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/security">431    Hardening guidance, credential rotation, and breach response.432  </Card>433434  <Card title="Troubleshooting" icon="wrench" href="https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/troubleshooting">435    Diagnose connectivity, TLS, and routing issues.436  </Card>437</CardGroup>438
Files main
Menu

Theme