SPB Git

Repository Public

overview.md 19.2 KB 399 lines markdown

1---2title: MCP tunnels3url: https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/overview4description: Securely connect Claude to MCP servers running in your private network without opening inbound ports or exposing services to the public internet.5---67MCP tunnels let you connect Claude to Model Context Protocol (MCP) servers that run inside your private network. Traffic flows over an outbound-only connection, so you don't need to open inbound firewall ports, expose services to the public internet, or allowlist Anthropic's IP ranges on your origin.89<Note>10  MCP tunnels are in research preview. [Request access](https://claude.com/form/mcp-tunnels) to try them. They are provided "as-is" without any uptime, support, or continuity commitment, and they depend on a third-party network provider (Cloudflare) that makes no availability commitment for the underlying transport. Anthropic may modify or discontinue MCP tunnels at any time.11</Note>1213For Zero Data Retention and HIPAA BAA eligibility, see [API and data retention](https://platform.claude.com/docs/en/manage-claude/api-and-data-retention#feature-eligibility).1415## How it works1617The [tunnel stack](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/concepts#components) is two components that run inside your network:1819* **[cloudflared](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/concepts#components):** Cloudflare's open-source tunnel connector. It initiates outbound-only connections to the [tunnel edge](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/concepts#components) and carries encrypted traffic from Anthropic to your proxy.20* **[Proxy](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/concepts#components):** Anthropic's routing component. It terminates [inner TLS](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/concepts#components), validates that upstream IPs fall within an allowed range, and routes each request to the correct [upstream MCP server](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/concepts#components) based on hostname.2122Each MCP server you expose gets a hostname under your tunnel domain (for example, `docs.<your-tunnel-domain>`). You attach these hostnames to a Managed Agent session in the Claude Console, or pass them to the Messages API through the [MCP connector](https://platform.claude.com/docs/en/agents-and-tools/mcp-connector).2324## Prerequisites2526Before deploying, make sure you have:2728* A deployment target: a Kubernetes cluster, or a VM with Docker and Docker Compose.2930* A tunnel. Create one in the Claude Console (see [Create a tunnel](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/console#create-a-tunnel)) or through the API; the Helm chart's setup hook can also create one for you during install.3132* A way for your stack to authenticate to the Tunnels API. Choose one:3334  * **[Programmatic access](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/concepts#credential-provisioning) (recommended).** Set up [Workload Identity Federation](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation) when you create the tunnel. 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 `workspace:manage_tunnels` scope.35  * **[Manual](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/concepts#credential-provisioning).** Supply static credentials yourself: the tunnel token from the Console and a server certificate signed by a CA you register there. See [Get the connection details](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/console#get-the-connection-details) and [Add a CA certificate](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/console#add-a-ca-certificate).3637* One or more MCP servers running in your private network. See [Remote MCP servers](https://platform.claude.com/docs/en/agents-and-tools/remote-mcp-servers) for examples.3839* Outbound connectivity as listed under [Network requirements](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/overview#network-requirements).4041### Network requirements4243| Component       | Destination                                          | Port / protocol  | Used during                     |44| --------------- | ---------------------------------------------------- | ---------------- | ------------------------------- |45| Setup component | `api.anthropic.com`                                  | 443 TCP          | Provisioning and token rotation |46| cloudflared     | Tunnel edge (`198.41.192.0/19`, `2606:4700:a0::/44`) | 7844 TCP and UDP | Runtime                         |47| Proxy           | Your upstream MCP servers                            | As configured    | Runtime                         |4849## Security model5051### Security layers5253Three independent layers protect every request:5455| Layer                                                                       | Protects against                                                         |56| --------------------------------------------------------------------------- | ------------------------------------------------------------------------ |57| Outer mTLS between Anthropic and the transport provider, with IP validation | Unauthorized clients reaching the tunnel                                 |58| Inner TLS from Anthropic's back end to your proxy                           | Payload inspection by the transport provider or any network intermediary |59| OAuth on each MCP server                                                    | Unauthorized use of MCP tools by authenticated tunnel traffic            |6061The tunnel transport runs on Cloudflare's network. Because the proxy terminates inner TLS using a certificate that only you hold, Cloudflare cannot read request or response payloads. Anthropic does not connect to a tunnel until a CA certificate is registered, so payloads are always encrypted when they cross Cloudflare's network. Cloudflare does receive connection metadata; see [What the transport provider can observe](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/overview#what-the-transport-provider-can-observe).6263### Shared responsibility model6465| Anthropic handles                                                         | Your organization handles                                                                                                                      |66| ------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |67| Tunnel access control                                                     | All content and traffic that transits your tunnel, and compliance with applicable third-party acceptable-use policies (including Cloudflare's) |68| Validating your CA certificate before connecting to your proxy            | Adherence to the deployment guidance on these pages                                                                                            |69| Ensuring Claude only sends requests to tunnels owned by your organization | Securing tunnel tokens and TLS private keys                                                                                                    |70|                                                                           | Managing the server certificate and renewing it before it expires                                                                              |71|                                                                           | Configuring OAuth on each MCP server                                                                                                           |72|                                                                           | Restricting network access for the proxy and MCP servers                                                                                       |73|                                                                           | Notifying Anthropic if you suspect a breach                                                                                                    |7475<Warning>76  If an attacker obtains your tunnel token **and** one of your TLS private keys, they could impersonate your proxy and read MCP request payloads. Treat both as high-value secrets. See [MCP tunnels security](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/security) for hardening guidance.77</Warning>7879### What the transport provider can observe8081Cloudflare provides the outbound transport. It cannot read MCP request or response payloads, but it does receive the following connection metadata:8283* the egress IP address of the host running cloudflared84* a cloudflared host fingerprint85* connection timing and byte-volume86* the `*.tunnel.anthropic.com` subdomain assigned to your tunnel8788Anthropic's agreement with Cloudflare restricts Cloudflare's use of this telemetry. Cloudflare acts as a subprocessor for this research preview.8990## Deploy a tunnel9192If you're new to MCP tunnels, start with the quickstart to get a working tunnel locally before configuring a production deployment.9394<CardGroup cols={2}>95  <Card title="Quickstart" icon="rocket" href="https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/quickstart">96    The shortest path to a working tunnel: Docker Compose with a sample MCP server.97  </Card>9899  <Card title="Deploy with Helm" icon="stack" href="https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/deploy-helm">100    Install on a Kubernetes cluster using the Anthropic Helm chart.101  </Card>102103  <Card title="Deploy with Docker Compose" icon="cube" href="https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/deploy-compose">104    Install on a VM using Docker Compose.105  </Card>106</CardGroup>107108Choosing between them:109110* **Deployment target**111112  * **Helm** when deploying to Kubernetes.113  * **Docker Compose** for a single host or local testing.114115* **Authentication for setup**116117  * **Programmatic access** (through Workload Identity Federation) when you have an OIDC identity provider such as a Kubernetes cluster, cloud IAM, or SPIFFE.118  * **Manual credentials** when you don't, or when you're testing.119120## Use the tunneled MCP servers121122Once your tunnel is active (it has an active CA certificate and your tunnel stack is connected), the upstream MCP servers are reachable from Claude Managed Agents and the Messages API.123124<Note>125  MCP tunnels created through the Console are not available as connectors in claude.ai.126</Note>127128In both cases, the tunnel carries encrypted traffic to your MCP server but does not authenticate to it. If the upstream MCP server requires its own authentication (OAuth, bearer token), supply it the same way you would for any other MCP server; it is independent of the tunnel.129130### Managed Agents (Console)1311321. In **Managed Agents > Sessions**, create a session and choose **Create new agent** so you can edit the MCP server list.1332. Click **+ MCP Server** and open the dropdown. Tunnels in the session's workspace that have at least one active certificate appear at the top of the list, above the public connector catalog.1343. Select the tunnel and supply the **Subdomain** that your proxy routes to a specific MCP server, and the **Path** the upstream MCP server expects. The **Resolves to** line shows the exact URL.135136### Messages API137138Pass the upstream MCP server's URL in the `mcp_servers` array, the same way as any other remote MCP server. The request body and `anthropic-beta` header follow the standard [MCP connector](https://platform.claude.com/docs/en/agents-and-tools/mcp-connector) format; only the `url` is tunnel-specific. The following example uses the MCP connector's `mcp-client` beta header, which is separate from the `mcp-tunnels` beta used by the [Tunnels API](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/reference). Make the request in the workspace the tunnel was created in by using an API key for that workspace or, if your key has access to multiple workspaces, by setting the [`anthropic-workspace-id` header](https://platform.claude.com/docs/en/manage-claude/authentication#select-a-workspace) to that workspace.139140The URL's host is `<subdomain>.<your-tunnel-domain>`. The path depends on your upstream MCP server, not the tunnel: FastMCP's `streamable-http` transport serves at `/mcp`, and other servers may use `/` or a custom path (check the server's documentation). The proxy forwards the path untouched.141142<CodeGroup>143  ```bash cURL144  curl https://api.anthropic.com/v1/messages \145    -H "Content-Type: application/json" \146    -H "X-API-Key: $ANTHROPIC_API_KEY" \147    -H "anthropic-version: 2023-06-01" \148    -H "anthropic-beta: mcp-client-2025-11-20" \149    -d '{150      "model": "claude-opus-5",151      "max_tokens": 1000,152      "messages": [{"role": "user", "content": "Use the hello tool to greet tunnel."}],153      "mcp_servers": [154        {155          "type": "url",156          "url": "https://echo.YOUR_TUNNEL_DOMAIN_HERE/mcp",157          "name": "echo"158        }159      ],160      "tools": [{"type": "mcp_toolset", "mcp_server_name": "echo"}]161    }'162  ```163164  ```bash CLI165  ant beta:messages create --beta mcp-client-2025-11-20 <<'YAML'166  model: claude-opus-5167  max_tokens: 1000168  messages:169    - role: user170      content: Use the hello tool to greet tunnel.171  mcp_servers:172    - type: url173      url: https://echo.YOUR_TUNNEL_DOMAIN_HERE/mcp174      name: echo175  tools:176    - type: mcp_toolset177      mcp_server_name: echo178  YAML179  ```180181  ```python Python182  client = anthropic.Anthropic()183184  response = client.beta.messages.create(185      model="claude-opus-5",186      max_tokens=1000,187      messages=[{"role": "user", "content": "Use the hello tool to greet tunnel."}],188      mcp_servers=[189          {190              "type": "url",191              "url": "https://echo.YOUR_TUNNEL_DOMAIN_HERE/mcp",192              "name": "echo",193          }194      ],195      tools=[{"type": "mcp_toolset", "mcp_server_name": "echo"}],196      betas=["mcp-client-2025-11-20"],197  )198199  print(response)200  ```201202  ```typescript TypeScript203  const anthropic = new Anthropic();204205  const response = await anthropic.beta.messages.create({206    model: "claude-opus-5",207    max_tokens: 1000,208    messages: [209      {210        role: "user",211        content: "Use the hello tool to greet tunnel."212      }213    ],214    mcp_servers: [215      {216        type: "url",217        url: "https://echo.YOUR_TUNNEL_DOMAIN_HERE/mcp",218        name: "echo"219      }220    ],221    tools: [222      {223        type: "mcp_toolset",224        mcp_server_name: "echo"225      }226    ],227    betas: ["mcp-client-2025-11-20"]228  });229230  console.log(response);231  ```232233  ```csharp C#234  AnthropicClient client = new();235236  var parameters = new MessageCreateParams237  {238      Model = Messages::Model.ClaudeOpus5,239      MaxTokens = 1000,240      Messages = new List<BetaMessageParam>241      {242          new() { Role = Role.User, Content = "Use the hello tool to greet tunnel." }243      },244      McpServers = new List<BetaRequestMcpServerUrlDefinition>245      {246          new()247          {248              Url = "https://echo.YOUR_TUNNEL_DOMAIN_HERE/mcp",249              Name = "echo"250          }251      },252      Tools = new List<BetaToolUnion>253      {254          new BetaMcpToolset("echo")255      },256      Betas = ["mcp-client-2025-11-20"]257  };258259  var message = await client.Beta.Messages.Create(parameters);260  Console.WriteLine(message);261  ```262263  ```go Go264  client := anthropic.NewClient()265266  response, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{267  	Model:     anthropic.ModelClaudeOpus5,268  	MaxTokens: 1000,269  	Messages: []anthropic.BetaMessageParam{270  		anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Use the hello tool to greet tunnel.")),271  	},272  	MCPServers: []anthropic.BetaRequestMCPServerURLDefinitionParam{273  		{274  			URL:  "https://echo.YOUR_TUNNEL_DOMAIN_HERE/mcp",275  			Name: "echo",276  		},277  	},278  	Tools: []anthropic.BetaToolUnionParam{279  		{OfMCPToolset: &anthropic.BetaMCPToolsetParam{280  			MCPServerName: "echo",281  		}},282  	},283  	Betas: []anthropic.AnthropicBeta{284  		anthropic.AnthropicBetaMCPClient2025_11_20,285  	},286  })287  if err != nil {288  	log.Fatal(err)289  }290  fmt.Println(response)291  ```292293  ```java Java294  import com.anthropic.models.beta.messages.BetaMcpToolset;295  // ...296  import com.anthropic.models.beta.messages.BetaRequestMcpServerUrlDefinition;297  // ...298299  void main() {300      AnthropicClient client = AnthropicOkHttpClient.fromEnv();301302      MessageCreateParams params = MessageCreateParams.builder()303          .model(Model.CLAUDE_OPUS_5)304          .maxTokens(1000L)305          .addUserMessage("Use the hello tool to greet tunnel.")306          .addMcpServer(BetaRequestMcpServerUrlDefinition.builder()307              .url("https://echo.YOUR_TUNNEL_DOMAIN_HERE/mcp")308              .name("echo")309              .build())310          .addTool(BetaMcpToolset.builder()311              .mcpServerName("echo")312              .build())313          .addBeta("mcp-client-2025-11-20")314          .build();315316      BetaMessage response = client.beta().messages().create(params);317      IO.println(response);318  }319  ```320321  ```php PHP322  $client = new Client();323324  $message = $client->beta->messages->create(325      maxTokens: 1000,326      messages: [327          ['role' => 'user', 'content' => 'Use the hello tool to greet tunnel.']328      ],329      model: 'claude-opus-5',330      mcpServers: [331          [332              'type' => 'url',333              'url' => 'https://echo.YOUR_TUNNEL_DOMAIN_HERE/mcp',334              'name' => 'echo',335          ],336      ],337      tools: [338          [339              'type' => 'mcp_toolset',340              'mcpServerName' => 'echo',341          ],342      ],343      betas: ['mcp-client-2025-11-20'],344  );345346  echo $message;347  ```348349  ```ruby Ruby350  client = Anthropic::Client.new351352  response = client.beta.messages.create(353    model: "claude-opus-5",354    max_tokens: 1000,355    messages: [356      { role: "user", content: "Use the hello tool to greet tunnel." }357    ],358    mcp_servers: [359      {360        type: "url",361        url: "https://echo.YOUR_TUNNEL_DOMAIN_HERE/mcp",362        name: "echo"363      }364    ],365    tools: [366      {367        type: "mcp_toolset",368        mcp_server_name: "echo"369      }370    ],371    betas: ["mcp-client-2025-11-20"]372  )373374  puts response375  ```376</CodeGroup>377378For authenticating to the upstream MCP server (`authorization_token`) and other `mcp_servers` options, see [MCP connector](https://platform.claude.com/docs/en/agents-and-tools/mcp-connector).379380## Next steps381382<CardGroup cols={2}>383  <Card title="Security" icon="lock" href="https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/security">384    Hardening guidance, credential rotation, and breach response.385  </Card>386387  <Card title="Troubleshooting" icon="wrench" href="https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/troubleshooting">388    Diagnose connectivity, TLS, and routing issues.389  </Card>390391  <Card title="Reference" icon="book" href="https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/reference">392    Proxy config fields, the Tunnels API, certificate requirements, and the setup component.393  </Card>394395  <Card title="MCP connector" icon="link" href="https://platform.claude.com/docs/en/agents-and-tools/mcp-connector">396    Use tunneled servers from the Messages API.397  </Card>398</CardGroup>399
Files main
Menu

Theme