Manage tunnels in the Console

Create tunnels, register CA certificates, retrieve the tunnel token, and attach tunneled MCP servers to agents from the Claude Console.

This page covers the Console side of an MCP tunnels deployment: creating a tunnel, registering your CA certificate, retrieving the tunnel token, and attaching the tunneled servers to an agent. Deploy MCP tunnels with Helm and Deploy MCP tunnels with Docker Compose cover running the stack inside your network.

Prerequisites

• One or more MCP servers running in your private network. The tunnel routes traffic to them; it does not host them.
• A role that can manage MCP tunnels, for creating and archiving tunnels, rotating the token, and managing certificates. Organization developers without it have read-only access to the MCP tunnels page and tunnel details.
• A way for your stack to authenticate to the Tunnels API. Choose one:
  • Programmatic access (recommended). Set up Workload Identity Federation during tunnel creation so your stack mints short-lived API tokens from your identity provider, fetches the tunnel token, and generates and registers a CA certificate automatically. Requires permission to manage federation rules, a registered OIDC issuer, and a federation rule with the org:manage_tunnels scope.
  • Manual. Skip programmatic access. After creating the tunnel, get the tunnel token, generate and register a CA certificate yourself, and supply the token and your server certificate to your deployment as secrets.

Create a tunnel

1. Open the MCP tunnels page

   In the Console sidebar, go to Manage > MCP tunnels.

2. Name the tunnel

   Click New tunnel and enter a name in the Create tunnel dialog. The name is required and identifies the tunnel in the list, on the detail page, and in the agent MCP server picker. A domain of the form abcd1234.tunnel.anthropic.com is assigned automatically.

3. Optionally set up programmatic access

   The Set up programmatic access toggle is off by default. To turn it on you need the following in place:

   1. Permission to manage federation rules. Tunnel management on its own doesn't grant this; if your role can create tunnels but not federation rules, the Console hides the toggle and shows a notice. The rest of the create flow is unchanged; your deployment will use the manual flow (get the tunnel token and register a CA from the Console after the tunnel is created).
   2. A registered OIDC issuer for the identity provider your stack will present tokens from (such as a Kubernetes cluster, AWS IAM, Google Cloud, or GitHub Actions). Register one under Settings > Workload identity > Issuers if your organization doesn't have one.
   3. A federation rule with the org:manage_tunnels scope. Turning on the toggle reveals a Federation rule picker; each rule shows the service account it binds to. Choose an existing rule scoped to tunnel management, or click Create federation rule to create one inline; the new-rule form lets you select the issuer and service account. The federation rule binds tokens from your issuer to a service account; the service account is the principal the Tunnels API sees.
   4. The rule's service account added to this workspace. Tunnels are workspace-scoped, and the Tunnels API authorizes against the service account's workspace memberships. If you're creating the tunnel in a workspace other than the organization's default, add the service account as a member of that workspace under Settings > Workspaces, and pass the workspace ID at deploy time (api.wif.workspaceId for Helm, ANTHROPIC_WORKSPACE_ID for Compose). See Workload Identity Federation for how rules, service accounts, and workspaces relate.

   Skipping this step is fully supported; both deploy guides have a Without programmatic access tab.

4. Create the tunnel

   Click Create tunnel. The Console provisions the tunnel and opens the detail page.

5. Record the deployment identifiers

   Both deploy paths need:

   • The tunnel ID (tnl_...), shown on the tunnel detail page.
   • The tunnel domain (abcd1234.tunnel.anthropic.com), shown on the tunnel detail page. Used as the proxy's tunnel_domain and in the server certificate's SAN.

   Without programmatic access, you also need the values your stack uses to connect and authenticate:

   • The tunnel token, revealed with the eye icon next to Token on the detail page. This authenticates the outbound connection to the tunnel; treat it as a secret. See Get the connection details.
   • A CA certificate that you generate and register on the tunnel.

   With programmatic access, your stack fetches the tunnel token through the Tunnels API and generates the CA and server certificate locally (the private key never leaves your environment), registering only the CA's public certificate with Anthropic. You're still responsible for securing the private keys and renewing the server certificate before it expires. Record the identifiers your stack needs to authenticate over Workload Identity Federation:

   • The federation rule ID (fdrl_...) of the rule you selected. The Console doesn't store the rule on the tunnel; find it later under Settings > Workload identity > Rules.
   • The organization ID (a UUID), shown under Settings > Organization.

Your organization can have up to 10 active tunnels. Creating a tunnel does not establish any connectivity; that happens once your stack dials in with the tunnel token and a CA certificate is registered.

Get the connection details

Open the tunnel. The detail page shows a Connection section with the domain and token and a Certificates section.

Add a CA certificate

Anthropic verifies inner TLS to your proxy against the CA certificates you register on the tunnel. A tunnel with no active certificates cannot accept connections, and does not appear in the agent MCP server picker until one is registered.

1. Find the Certificates section

   On the tunnel's detail page, scroll to the Certificates section and click Add certificate.

2. Provide the certificate

   Either click Choose file and select a .pem, .crt, or .cer file, drag the file onto the text area, or paste the PEM block directly. The modal rejects private-key material and content that isn't a -----BEGIN CERTIFICATE----- block. The file must be 8 kB or smaller.

3. Add the certificate

   Click Add certificate. The fingerprint and expiry appear in the certificate list, and the slot count on the section header increments.

A tunnel holds up to two active certificates so you can rotate without downtime: register the new certificate alongside the old one, redeploy your proxy with the new key pair, confirm traffic is flowing, then click Revoke on the old certificate's row. Revoked certificates remain visible in the list with a Revoked badge.

Deploy the stack

The tunnel exists in the Console, but no traffic flows until the stack is running inside your network and dialed in with the tunnel token. Follow one of the deploy guides:

Use the tunnel in an agent

Once your stack is running and has one or more MCP servers configured, attach a tunneled MCP server to a Managed Agent session. To call the same servers from the Messages API instead, see Use the tunneled MCP servers.

1. Open the New session modal

   Go to Managed Agents > Sessions and click New session.

2. Define an inline agent

   In the agent picker, choose Create new agent so you can edit the MCP server list directly.

3. Add the MCP server

   Click + MCP Server and open the dropdown. Tunnels created in the current workspace appear at the top of the list, above the public connector catalog. Select the tunnel that fronts the server you want to reach.

4. Supply the routing

   The card shows two optional fields: Subdomain (prefixed to the tunnel domain) and Path (appended after it). Enter whichever your proxy's routes use. The Resolves to line shows the exact URL that will be written to agent.mcp_servers.

Archive a tunnel

Archiving immediately stops the tunnel from accepting connections and is permanent.

In the MCP tunnels list, open the row menu for the tunnel and choose Archive. Archived tunnels remain visible when you filter the list by Archived or All.

Next steps