SPB Git

Repository Public

quickstart.md 11.2 KB 287 lines markdown

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
Files main
Menu

Theme