Repository Public
1---2title: MCP tunnels quickstart3url: https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/quickstart4description: Connect Claude to a private MCP server using a local Docker Compose deployment.5---67<Note>8 MCP tunnels are in research preview. [Request access](https://claude.com/form/mcp-tunnels) to try them.9</Note>1011This quickstart takes you from zero to Claude calling a private MCP server through a tunnel. It uses Docker Compose with [manual](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/concepts#credential-provisioning) credential provisioning, which is the shortest path for local testing. For production deployments, see [Deploy with Helm](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/deploy-helm) or [Deploy with Docker Compose](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/deploy-compose).1213## What you'll build1415A two-container [tunnel stack](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/concepts#components) (the [proxy](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/concepts#components) and [cloudflared](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/concepts#components)) plus a sample MCP server running alongside it. When everything is running, the sample server is reachable from Claude at `https://echo.<your-tunnel-domain>/mcp` even though nothing is listening on a public port.1617## What you need1819* [Docker and Docker Compose](https://docs.docker.com/get-docker/) on a machine with outbound internet access.20* A role in the [Claude Console](https://platform.claude.com) that can manage MCP tunnels. See the [Console guide prerequisites](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/console#prerequisites).21* [OpenSSL](https://openssl-library.org/source/) 1.1.1 or later. Preinstalled on macOS and most Linux distributions; on Windows, install it separately (the `openssl` binary must be on your `PATH`).2223<Steps>24 <Step title="Create a tunnel">25 In the Claude Console sidebar, go to **Manage > MCP tunnels** and click **New tunnel**. Give it a name. Leave **Set up programmatic access** off; this quickstart uses manual credential provisioning.2627 After it's created, open the tunnel. Copy two values from the **Connection** section:2829 * **Domain** (looks like `abcd1234.tunnel.anthropic.com`)30 * **Token** (click the eye icon, then copy)31 </Step>3233 <Step title="Set up the deployment directory">34 <Tabs>35 <Tab title="macOS / Linux">36 ```bash37 mkdir -p mcp-tunnel/{config,data}38 cd mcp-tunnel39 export TUNNEL_DOMAIN=YOUR_TUNNEL_DOMAIN_HERE # from step 140 export TUNNEL_TOKEN='eyJ...' # from step 141 ```42 </Tab>4344 <Tab title="Windows (PowerShell)">45 ```powershell46 New-Item -ItemType Directory -Force -Path mcp-tunnel/config, mcp-tunnel/data | Out-Null47 Set-Location mcp-tunnel48 $env:TUNNEL_DOMAIN = "YOUR_TUNNEL_DOMAIN_HERE" # from step 149 $env:TUNNEL_TOKEN = "eyJ..." # from step 150 ```51 </Tab>52 </Tabs>53 </Step>5455 <Step title="Generate a CA and server certificate">56 The proxy terminates [inner TLS](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/concepts#components) using a certificate signed by a CA you control. Generate both:5758 <Tabs>59 <Tab title="macOS / Linux">60 ```bash61 openssl req -x509 -newkey rsa:2048 -nodes \62 -keyout data/ca.key -out data/ca.crt \63 -days 3650 -subj "/CN=mcp-tunnel-ca" \64 -addext "basicConstraints=critical,CA:TRUE" \65 -addext "keyUsage=critical,keyCertSign,cRLSign" \66 -addext "subjectKeyIdentifier=hash"6768 cat > data/tls.ext <<EOF69 subjectAltName = DNS:${TUNNEL_DOMAIN},DNS:*.${TUNNEL_DOMAIN}70 authorityKeyIdentifier = keyid,issuer71 extendedKeyUsage = serverAuth72 EOF7374 openssl req -newkey rsa:2048 -nodes \75 -keyout data/tls.key -out /tmp/server.csr \76 -subj "/CN=${TUNNEL_DOMAIN}"77 openssl x509 -req -in /tmp/server.csr \78 -CA data/ca.crt -CAkey data/ca.key -CAcreateserial \79 -out data/tls.crt -days 90 -extfile data/tls.ext8081 chmod 644 data/tls.key82 ```83 </Tab>8485 <Tab title="Windows (PowerShell)">86 ```powershell87 openssl req -x509 -newkey rsa:2048 -nodes `88 -keyout data/ca.key -out data/ca.crt `89 -days 3650 -subj "/CN=mcp-tunnel-ca" `90 -addext "basicConstraints=critical,CA:TRUE" `91 -addext "keyUsage=critical,keyCertSign,cRLSign" `92 -addext "subjectKeyIdentifier=hash"9394 @"95 subjectAltName = DNS:$env:TUNNEL_DOMAIN,DNS:*.$env:TUNNEL_DOMAIN96 authorityKeyIdentifier = keyid,issuer97 extendedKeyUsage = serverAuth98 "@ | Set-Content -NoNewline -Encoding ascii -Path data/tls.ext99100 openssl req -newkey rsa:2048 -nodes `101 -keyout data/tls.key -out data/server.csr `102 -subj "/CN=$env:TUNNEL_DOMAIN"103 openssl x509 -req -in data/server.csr `104 -CA data/ca.crt -CAkey data/ca.key -CAcreateserial `105 -out data/tls.crt -days 90 -extfile data/tls.ext106 ```107 </Tab>108 </Tabs>109110 Back in the Console, on the tunnel detail page, click **Add certificate** and upload `data/ca.crt` (or paste its contents). The tunnel status flips to **Active**.111 </Step>112113 <Step title="Write the sample MCP server">114 <Tabs>115 <Tab title="macOS / Linux">116 ```bash117 cat > hello_server.py <<'EOF'118 from mcp.server.fastmcp import FastMCP119120 mcp = FastMCP("hello-server", host="0.0.0.0", port=9000)121122123 @mcp.tool()124 def hello(name: str = "world") -> str:125 """Say hello to someone."""126 return f"Hello, {name}!"127128129 if __name__ == "__main__":130 mcp.run(transport="streamable-http")131 EOF132 ```133 </Tab>134135 <Tab title="Windows (PowerShell)">136 ```powershell137 @'138 from mcp.server.fastmcp import FastMCP139140 mcp = FastMCP("hello-server", host="0.0.0.0", port=9000)141142143 @mcp.tool()144 def hello(name: str = "world") -> str:145 """Say hello to someone."""146 return f"Hello, {name}!"147148149 if __name__ == "__main__":150 mcp.run(transport="streamable-http")151 '@ | Set-Content -NoNewline -Encoding ascii -Path hello_server.py152 ```153 </Tab>154 </Tabs>155 </Step>156157 <Step title="Write the proxy config and compose file">158 <Tabs>159 <Tab title="macOS / Linux">160 ```bash161 cat > config/mcp-proxy.yaml <<EOF162 listen_addr: ":8080"163 tunnel_domain: ${TUNNEL_DOMAIN}164 tls:165 cert_file: /data/tls.crt166 key_file: /data/tls.key167 routes:168 echo: http://hello-mcp:9000169 EOF170171 cat > docker-compose.yaml <<'EOF'172 services:173 mcp-proxy:174 image: us-docker.pkg.dev/anthropic-public-registry/images/mcp-proxy@sha256:efb27b299d627e4134815663cb8896641eeaee025d734c0f695582b4df38f013175 volumes:176 - ./config/mcp-proxy.yaml:/etc/mcp-gateway/config.yaml:ro177 - ./data:/data:ro178 restart: unless-stopped179180 cloudflared:181 image: cloudflare/cloudflared@sha256:6b599ca3e974349ead3286d178da61d291961182ec3fe9c505e1dd02c8ac31b0182 command: tunnel --no-autoupdate run --url http://localhost:8080183 environment:184 - TUNNEL_TOKEN185 network_mode: "service:mcp-proxy"186 restart: unless-stopped187188 hello-mcp:189 image: python:3.13-slim190 working_dir: /app191 volumes:192 - ./hello_server.py:/app/hello_server.py:ro193 command: sh -c "pip install --quiet mcp && python hello_server.py"194 restart: unless-stopped195 EOF196 ```197 </Tab>198199 <Tab title="Windows (PowerShell)">200 ```powershell201 @"202 listen_addr: ":8080"203 tunnel_domain: $env:TUNNEL_DOMAIN204 tls:205 cert_file: /data/tls.crt206 key_file: /data/tls.key207 routes:208 echo: http://hello-mcp:9000209 "@ | Set-Content -NoNewline -Encoding ascii -Path config/mcp-proxy.yaml210211 @'212 services:213 mcp-proxy:214 image: us-docker.pkg.dev/anthropic-public-registry/images/mcp-proxy@sha256:efb27b299d627e4134815663cb8896641eeaee025d734c0f695582b4df38f013215 volumes:216 - ./config/mcp-proxy.yaml:/etc/mcp-gateway/config.yaml:ro217 - ./data:/data:ro218 restart: unless-stopped219220 cloudflared:221 image: cloudflare/cloudflared@sha256:6b599ca3e974349ead3286d178da61d291961182ec3fe9c505e1dd02c8ac31b0222 command: tunnel --no-autoupdate run --url http://localhost:8080223 environment:224 - TUNNEL_TOKEN225 network_mode: "service:mcp-proxy"226 restart: unless-stopped227228 hello-mcp:229 image: python:3.13-slim230 working_dir: /app231 volumes:232 - ./hello_server.py:/app/hello_server.py:ro233 command: sh -c "pip install --quiet mcp && python hello_server.py"234 restart: unless-stopped235 '@ | Set-Content -NoNewline -Encoding ascii -Path docker-compose.yaml236 ```237 </Tab>238 </Tabs>239 </Step>240241 <Step title="Start it">242 <Tabs>243 <Tab title="macOS / Linux">244 ```bash245 docker compose up -d246 docker compose logs mcp-proxy | grep "route configured"247 docker compose logs cloudflared | grep "Registered tunnel connection"248 ```249 </Tab>250251 <Tab title="Windows (PowerShell)">252 ```powershell253 docker compose up -d254 docker compose logs mcp-proxy | Select-String "route configured"255 docker compose logs cloudflared | Select-String "Registered tunnel connection"256 ```257 </Tab>258 </Tabs>259260 You should see one `route configured` line for `echo` and four `Registered tunnel connection` lines. The containers take a few seconds to start; rerun the log commands if they come back empty.261 </Step>262263 <Step title="Call it from Claude">264 In the Console, go to **Managed Agents > Sessions** and create a session. In the agent picker choose **Create new agent**, give the agent a name, and keep the pre-filled model. Click **+ MCP Server**, select your tunnel, set **Subdomain** to `echo` and **Path** to `mcp`. Then ask:265266 > Use the hello tool to greet tunnel.267268 You should see a tool call followed by its result.269 </Step>270</Steps>271272## Next steps273274The tunnel is verified end to end. To swap in your own MCP server, add it to `docker-compose.yaml` (or run it on the same Docker network), add a route for it in `config/mcp-proxy.yaml`, then restart the proxy (`docker compose restart mcp-proxy`).275276For production deployments:277278<CardGroup cols={2}>279 <Card title="Deploy with Docker Compose" icon="cube" href="https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/deploy-compose">280 Hardened single-host deployment, with or without programmatic access.281 </Card>282283 <Card title="Deploy with Helm" icon="stack" href="https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/deploy-helm">284 Kubernetes deployment with automatic credential management.285 </Card>286</CardGroup>287