SPB Git

Repository Public

security.md 5.5 KB 114 lines markdown

1---2title: MCP tunnels security3url: https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/security4description: Hardening guidance, credential rotation, breach response, and teardown for MCP tunnel deployments.5---67<Note>8  MCP tunnels are in research preview. [Request access](https://claude.com/form/mcp-tunnels) to try them.9</Note>1011The tunnel architecture provides strong defaults (outbound-only connectivity, end-to-end encryption, and IP validation), but the overall security of your [tunnel stack](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/concepts#components) also depends on how you configure and operate it. This page covers recommended hardening, breach response, and how to decommission a tunnel.1213## Best practices1415* **Require OAuth on every MCP server.** Configure each [upstream MCP server](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/concepts#components) to require OAuth as described in the [MCP authorization spec](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization). OAuth provides defense in depth on top of the tunnel's transport authentication and enables user-level authorization at the data layer.16* **Enable SSO for your organization.** Tunnels, federation rules, and service accounts are managed in the Claude Console. SSO enforces your identity provider's session controls on the admins who can change them.17* **Restrict `upstream.allowed_ips`.** Use the smallest CIDR ranges that cover your MCP servers. This is the [proxy](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/concepts#components)'s primary SSRF defense.18* **Monitor logs.** Alert on warnings, errors, and unusual traffic patterns from the tunnel stack.19* **Rotate credentials.** Rotate the server certificate and tunnel token on a regular schedule, and immediately if you suspect compromise.20* **Keep images updated.** Track new proxy releases and pin images by SHA-256 digest.21* **Limit network reach.** The proxy and [cloudflared](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/concepts#components) should only be able to reach the destinations listed in the [network requirements](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/overview#network-requirements). Use NetworkPolicy (Kubernetes) or host firewall rules (Compose).22* **Limit MCP server scope.** Each server should expose only the tools and data required for its purpose.23* **Protect credentials at rest.** Apply your organization's secrets-management practices to private keys and tunnel tokens.2425## Respond to a suspected breach2627If you believe your tunnel token, TLS keys, or proxy host has been compromised:2829<Steps>30  <Step title="Stop the tunnel stack">31    <Tabs>32      <Tab title="Helm">33        ```bash34        helm uninstall mcp-tunnel -n mcp-tunnel35        ```36      </Tab>3738      <Tab title="Docker Compose">39        ```bash40        docker compose down --timeout 041        ```42      </Tab>43    </Tabs>44  </Step>4546  <Step title="Detach the upstream MCP servers">47    Remove the upstream MCP servers from any Managed Agent sessions that use them, and stop passing their URLs in the `mcp_servers` block of Messages API requests.48  </Step>4950  <Step title="Archive the tunnel">51    Archiving invalidates the tunnel token and detaches the domain. In the Console, [archive the tunnel](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/console#archive-a-tunnel) from the **MCP tunnels** list. To archive over the API instead, see [Archive a tunnel](https://platform.claude.com/docs/en/api/beta/tunnels/archive).52  </Step>5354  <Step title="Contact Anthropic">55    Report the suspected compromise to Anthropic support.56  </Step>5758  <Step title="Rotate downstream credentials">59    Re-provision a fresh tunnel and rotate any OAuth tokens that the affected MCP servers issued.60  </Step>6162  <Step title="Review logs before restoring service">63    Inspect proxy, cloudflared, and MCP server logs for the window of suspected compromise before bringing the new tunnel online.64  </Step>65</Steps>6667## Tear down a tunnel6869Follow these steps to decommission a tunnel and remove all stored credentials.7071<Steps>72  <Step title="Stop the tunnel stack">73    <Tabs>74      <Tab title="Helm">75        ```bash76        helm uninstall mcp-tunnel -n mcp-tunnel77        ```78      </Tab>7980      <Tab title="Docker Compose">81        ```bash82        docker compose down83        ```84      </Tab>85    </Tabs>86  </Step>8788  <Step title="Archive the tunnel">89    In the Console, [archive the tunnel](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/console#archive-a-tunnel) from the **MCP tunnels** list.90  </Step>9192  <Step title="Remove stored credentials">93    <Tabs>94      <Tab title="Helm">95        With programmatic access, the setup component created a single Secret named after the release. Without programmatic access, you created `mcp-tunnel-token` and `mcp-tunnel-cert` yourself. Delete whichever apply:9697        ```bash98        kubectl -n mcp-tunnel delete secret \99          mcp-tunnel mcp-tunnel-token mcp-tunnel-cert \100          --ignore-not-found101        ```102      </Tab>103104      <Tab title="Docker Compose">105        Private keys and certificates live in `data/`. The tunnel token lives in `data/tunnel-token` (programmatic flow) or in your shell environment (manual flow). The `config/` directory and `docker-compose.yaml` contain no secrets; keep them if you plan to re-provision, or remove them as well.106107        ```bash108        sudo rm -rf data109        ```110      </Tab>111    </Tabs>112  </Step>113</Steps>114
Files main
Menu

Theme