Tunnels & Relay

mcpr includes a built-in tunnel that gives your local MCP server a public HTTPS URL. Tunnels are a development convenience — they let remote AI clients (ChatGPT, Claude) reach your local machine without a public IP, port forwarding, or ngrok.

For production, use direct HTTP mode instead.

When to use a tunnel

Scenario	Why you need a tunnel
Local development	Your laptop doesn’t have a public IP, but ChatGPT needs one
NAT / firewall	Can’t open inbound ports on your network
Quick sharing	Give a colleague or AI client a URL that works immediately
Testing with remote AI clients	ChatGPT and Claude need a public HTTPS endpoint

You do not need a tunnel for local clients like Claude Desktop, VS Code, or Cursor — use --port 3000 instead.

Basic usage

mcpr --mcp http://localhost:9000
# → Tunnel: https://abc123.tunnel.mcpr.app

Use the tunnel URL in ChatGPT, Claude, or any MCP client. mcpr routes all traffic through the proxy core — routing, structured events, and CSP handling all work the same as direct HTTP mode.

How it works

mcpr opens a persistent WebSocket connection to a relay server. When an AI client sends a request to your tunnel URL, the relay forwards it through the WebSocket to mcpr on your machine. mcpr processes it and sends the response back.

AI Client → relay (tunnel.mcpr.app) → WebSocket → mcpr (your machine) → MCP Server

The AI client never connects to your machine directly. All traffic flows through the relay.

Stable URLs

On first run, mcpr generates a tunnel token and saves it to mcpr.toml. Your URL stays the same across restarts:

# mcpr.toml (auto-generated on first run)
mcp = "http://localhost:9000"
tunnel_token = "tok_abc123..."

Configure your AI client once, keep developing. The URL doesn’t change unless you delete the token.

Cloud tunnels

mcpr Cloud adds managed tunnel infrastructure on top:

• Persistent URLs — your URL survives across machines, not just restarts
• Custom subdomains — claim yourapp.tunnel.mcpr.app instead of a random hash
• Token management — rotate tokens, manage subdomains from a dashboard

See Custom Subdomains and Tunnel Tokens.

Self-hosted relay

Run your own relay server instead of using tunnel.mcpr.app.

With Docker

docker run -d \
  -p 8080:8080 \
  ghcr.io/cptrodgers/mcpr:latest \
  --relay --port 8080 --relay-domain tunnel.yourdomain.com

With auth provider (production):

docker run -d \
  -p 8080:8080 \
  -e MCPR_AUTH_PROVIDER=https://api.yourdomain.com \
  -e MCPR_AUTH_PROVIDER_SECRET=your-secret \
  ghcr.io/cptrodgers/mcpr:latest \
  --relay --port 8080 --relay-domain tunnel.yourdomain.com

With a config file:

docker run -d \
  -p 8080:8080 \
  -v /path/to/mcpr.toml:/app/mcpr.toml \
  ghcr.io/cptrodgers/mcpr:latest \
  --relay --port 8080

Without Docker

mcpr --relay --relay-domain tunnel.yourdomain.com --port 8080

Then point your proxy at it:

mcpr --mcp http://localhost:9000 --relay-url https://tunnel.yourdomain.com

Requirements

• A VPS or server with a public IP
• Wildcard DNS (*.tunnel.yourdomain.com → your server)
• TLS termination (Nginx, Caddy, or built-in)

Auth modes

The relay supports three auth modes:

Mode	Config	When to use
Open	No tokens, no auth_provider	Local dev, testing
Static tokens	[[relay.tokens]] entries	Small team, simple setup
Auth provider	[relay].auth_provider URL	Dynamic token management at scale

See the relay deployment guide and auth provider spec for full setup instructions.