mcpTunnel Docs

mcpTunnel discovers your locally configured MCP servers, aggregates their tools into a single endpoint, and tunnels it to the internet via Cloudflare. Any MCP-compatible AI client — ChatGPT, Claude, Cursor, and more — can then access your local tools remotely.

Pre-built Binaries

Download the latest release for your platform from GitHub Releases:

# Linux & macOS — auto-detect platform
curl -L https://github.com/appsecsanta/mcp-tunnel/releases/latest/download/mcptunnel-$(uname -s | tr A-Z a-z)-$(uname -m) -o mcptunnel
chmod +x mcptunnel
sudo mv mcptunnel /usr/local/bin/

From Source (Go)

Requires Go 1.21 or later:

go install github.com/appsecsanta/mcptunnel@latest

Verify Installation

mcptunnel --version

The fastest way to expose your MCP servers to an AI client:

mcptunnel start

https://api.mcptunnel.sh/mcp

mcpTunnel automatically discovers MCP servers from your existing AI tool configurations. No manual setup required.

Supported Sources

By default, mcpTunnel scans all sources. Use --source to limit discovery to a specific one:

# Only discover from Claude Desktop config
mcptunnel start --source claude

For servers not defined in any supported config file, create a custom definition at ~/.mcptunnel/servers.json:

{
  "mcpServers": {
    "my-custom-server": {
      "command": "node",
      "args": ["/path/to/server.js"],
      "env": {
        "API_KEY": "your-key"
      }
    },
    "python-tools": {
      "command": "python",
      "args": ["-m", "my_mcp_server"],
      "env": {}
    }
  }
}

Server Definition Fields

mcptunnel start

Discovers MCP servers, starts the aggregating HTTP server, and opens a tunnel.

mcptunnel login

Authenticate with the mcpTunnel service for named tunnels and dashboard access.

mcptunnel login

mcptunnel --version

Print the installed version of mcpTunnel.

mcpTunnel uses Cloudflare tunnels to expose your local server to the internet without port forwarding, firewall rules, or a public IP address.

Quick Tunnel (default)

Generates a temporary random URL. No account required.

mcptunnel start --quick-tunnel

Named Tunnel

Persistent URL that stays the same across restarts. Requires authentication.

mcptunnel login
mcptunnel start --named-tunnel my-dev-machine

Local Only (No Tunnel)

Run the HTTP server on localhost without creating a tunnel. Useful for LAN access or when using your own reverse proxy.

mcptunnel start --no-tunnel --port 8080

mcpTunnel merges tools, resources, and prompts from all discovered MCP servers into a single endpoint. Tool names are prefixed with the server name to prevent collisions.

Naming Convention

Tools are namespaced with a double-underscore prefix: servername__toolname

# Example: 3 servers aggregated
filesystem__read_file
filesystem__write_file
filesystem__list_directory
git__log
git__diff
git__status
postgres__query
postgres__list_tables

MCP Endpoint

The aggregated server is available at /mcp using Streamable HTTP transport (MCP 2025-03-26 spec). JSON-RPC over HTTP with session management headers.

Credential Guard

mcpTunnel scans each server's environment variables for patterns that look like secrets (API keys, tokens, passwords). Servers with detected credentials trigger a warning.

# Skip any server with detected credentials
mcptunnel start --safe-only

OAuth Authentication

Named tunnels support OAuth 2.0 authentication, requiring clients to authenticate before accessing your MCP servers. Quick tunnels are publicly accessible by URL — treat the URL as a secret.

Best Practices

• Use --safe-only in production to skip servers with credentials
• Prefer named tunnels with OAuth for persistent access
• Never share quick tunnel URLs publicly — they grant full tool access
• Review discovered servers before starting the tunnel
• Use --verbose to inspect what tools and resources are being exposed

Instructions for connecting mcpTunnel to each supported AI client.