Tunnels

mcpr ships a tunnel client 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, run mcpr in direct HTTP mode instead — bind to a port and put it behind your load balancer or reverse proxy.

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. Leave [tunnel].enabled = false (the default) for proxy-only mode.

Basic usage

The tunnel is disabled by default. Enable it explicitly with [tunnel].enabled = true and provide a token. Register at mcpr.app to get one.

mcp = "http://localhost:9000"

[tunnel]
enabled = true
token   = "your-tunnel-token"

mcpr proxy run mcpr.toml
# → ready: mcpr proxy running on http://localhost:3004 -> http://localhost:9000
# → tunnel: public URL: 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, observability, 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

Your URL stays the same as long as the token does. The default subdomain is derived from the token — opaque, but stable across restarts. To use a friendly fixed subdomain, claim one in mcpr Cloud (see Custom Subdomains) and add it to your config:

[tunnel]
enabled   = true
token     = "your-tunnel-token"
subdomain = "myapp"

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

Cloud tunnels

mcpr Cloud adds managed tunnel infrastructure on top:

• Custom subdomains — claim yourapp.tunnel.mcpr.app instead of a random hash
• Token management — rotate tokens, manage subdomains from the dashboard
• Persistent across machines — same URL on a new laptop, same URL in CI

See Custom Subdomains and Tunnel Tokens.

Self-hosted relay

Want to run your own relay? The relay server lives in a separate repo at pragmalabs-tech/mcp-tunnel. Once it’s running, point the proxy at it via [tunnel].relay_url:

mcp = "http://localhost:9000"

[tunnel]
enabled   = true
relay_url = "https://tunnel.yourdomain.com"
token     = "your-token"