Using rustunnel from an AI agent or LLM harness

rustunnel ships an MCP server (rustunnel-mcp) that exposes tunnel management as tools any Model Context Protocol client can call. Once it’s wired into your harness, you can just say:

“Create an HTTP tunnel to my service on port 3000.” “Expose port 5432 over TCP so I can reach my database.” “Spin up a load-balanced pool across ports 3000 and 3001 with a health check.”

This guide is the one-stop reference for adding rustunnel to Claude Code, Claude Desktop, Codex, Cursor, Windsurf, Cline, or any custom MCP agent. For the deeper server and tool reference, see the MCP server guide.

1. Prerequisites

You need two binaries on your PATH:

rustunnel — the client (the MCP server spawns it to open tunnels)
rustunnel-mcp — the MCP server itself

# Homebrew (macOS / Linux)
brew tap joaoh82/rustunnel && brew install rustunnel

# Or build from source
git clone https://github.com/joaoh82/rustunnel.git && cd rustunnel
make release          # builds rustunnel, rustunnel-server, rustunnel-mcp
sudo install -m755 target/release/rustunnel     /usr/local/bin/rustunnel
sudo install -m755 target/release/rustunnel-mcp /usr/local/bin/rustunnel-mcp

2. Get an API token (one-time)

This is the one required user step. Everything else is config you can copy-paste.

rustunnel requires an API token. You only need to do this once.

Hosted (rustunnel.com): sign up free at rustunnel.com, then go to Dashboard → API Keys and create a key. No waiting list.
Self-hosted: run rustunnel token create --name agent --server <host>:4040 --admin_token <admin>, or create one from your dashboard.

Set it as RUSTUNNEL_TOKEN in the MCP config below. When that variable is set, the agent never has to pass the token on individual calls.

3. The two server settings

Setting	Hosted example	Self-hosted example	Local dev
`--server` (control plane)	`eu.edge.rustunnel.com:4040`	`tunnel.example.com:4040`	`localhost:4040`
`--api` (dashboard REST API)	`https://eu.edge.rustunnel.com:8443`	`https://tunnel.example.com:8443`	`http://localhost:4041`

Add --insecure only for local dev with self-signed certs.

4. Quick install (any harness)

The installer prompts for your token and writes the right config for the harness you pick:

curl -fsSL https://raw.githubusercontent.com/joaoh82/rustunnel/main/integrations/install.sh | bash
# or, from a clone:
./integrations/install.sh

It supports claude-code, claude-desktop, codex, cursor, windsurf, cline, and generic (prints a snippet). Run ./integrations/install.sh --help for non-interactive flags.

5. Per-harness configuration

Ready-to-edit templates live in the integrations/ folder. In every template, replace the placeholder token with your own, and swap the --server / --api values if you self-host.

Claude Code

Plugin (recommended — zero config):

/plugin install rustunnel
/plugin configure rustunnel     # prompts for server, API URL, token

See the Claude Code plugin guide. Manual .mcp.json in your project root — see the template:

{
  "mcpServers": {
    "rustunnel": {
      "command": "rustunnel-mcp",
      "args": ["--server", "eu.edge.rustunnel.com:4040", "--api", "https://eu.edge.rustunnel.com:8443"],
      "env": { "RUSTUNNEL_TOKEN": "<your-token>" }
    }
  }
}

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows). Use the same mcpServers shape as above — template.

Codex (OpenAI)

Codex reads MCP servers from ~/.codex/config.toml — template:

[mcp_servers.rustunnel]
command = "rustunnel-mcp"
args = ["--server", "eu.edge.rustunnel.com:4040", "--api", "https://eu.edge.rustunnel.com:8443"]
env = { RUSTUNNEL_TOKEN = "<your-token>" }

Codex also reads an AGENTS.md at the repo root for guidance.

Cursor

Project: .cursor/mcp.json. Global: ~/.cursor/mcp.json. Same mcpServers shape — template.

Windsurf

~/.codeium/windsurf/mcp_config.json. Same shape — template.

Cline (VS Code)

cline_mcp_settings.json (via the Cline MCP settings UI). Same shape — template.

Generic / custom agent

Any MCP client uses the same command + args + env. Use the generic template. For a programmatic agent, spawn rustunnel-mcp and speak newline-delimited JSON-RPC 2.0 over stdin/stdout:

import subprocess, json, os

proc = subprocess.Popen(
    ["rustunnel-mcp", "--server", "eu.edge.rustunnel.com:4040",
     "--api", "https://eu.edge.rustunnel.com:8443"],
    stdin=subprocess.PIPE, stdout=subprocess.PIPE,
    env={**os.environ, "RUSTUNNEL_TOKEN": "<your-token>"},
)

def call(method, params=None, _id=[0]):
    _id[0] += 1
    msg = {"jsonrpc": "2.0", "id": _id[0], "method": method}
    if params: msg["params"] = params
    proc.stdin.write(json.dumps(msg).encode() + b"\n"); proc.stdin.flush()
    return json.loads(proc.stdout.readline())

call("initialize", {"protocolVersion": "2024-11-05"})
print(call("tools/call", {"name": "create_tunnel",
      "arguments": {"local_port": 3000, "protocol": "http"}}))

6. Available tools

Every authenticated tool accepts an optional token argument. Omit it when RUSTUNNEL_TOKEN is set in the MCP config.

Tool	Purpose
`create_tunnel`	Open a tunnel and get a public URL. HTTP/TCP/UDP, P2P, and load-balanced pools
`close_tunnel`	Close a tunnel by ID
`list_tunnels`	List active tunnels
`get_tunnel_history`	Past tunnel activity (audit)
`list_regions`	Available server regions (no auth)
`get_connection_info`	CLI command / config for manual runs (cloud sandboxes)

`create_tunnel` arguments

Argument	When	Description
`local_port`	always	Local port the service listens on
`protocol`	always	`http`, `tcp`, `udp`, or `p2p`
`token`	optional	Falls back to `RUSTUNNEL_TOKEN`
`subdomain`	http	Custom subdomain
`region`	optional	`eu` / `us` / `ap`; omit to auto-select
`local_host`	optional	Forward to another host (default `localhost`)
`secret`	p2p	Shared secret (publisher and subscriber match)
`peer_name`	p2p publish	Publish under this name
`peer_target`	p2p connect	Connect to this published name
`group` + `group_key`	load balancing	Join a pool (http/tcp); members share the key
`health_check`	optional	`{ type: tcp\|http, path, interval_secs, timeout_secs, max_failed, expect_2xx, alert_webhook }`

See the MCP server guide for the full tool reference, load balancing for pools and health checks, and P2P tunnels for peer-to-peer details.

7. Security notes

Tokens travel to the server over HTTPS. Use --insecure only in local dev.
The RUSTUNNEL_TOKEN env var keeps the token out of tool-call payloads and chat history — prefer it over passing token inline.
Child rustunnel processes spawned by create_tunnel are killed when the MCP server exits; temp config files for load-balanced tunnels are cleaned up too.
Protect any config file you save: chmod 600 ~/.rustunnel/config.yml.

MCP server

Full reference for rustunnel-mcp: every tool, parameter, and response shape.

Claude Code plugin

Skip the manual config — install the plugin with one command in Claude Code.

Load balancing

How load-balanced pools and health checks work for tunnels your agent creates.

P2P tunnels

Direct peer-to-peer tunnels with shared secrets and named peers.

AI tools hub

Per-harness setup pages — Claude Code, Cursor, Windsurf, generic MCP — with agent-ready prompts.

Agent manual

Copy-paste recipes and an FAQ for AI agents, served as plain markdown.

​1. Prerequisites

​2. Get an API token (one-time)

​3. The two server settings

​4. Quick install (any harness)

​5. Per-harness configuration

​Claude Code

​Claude Desktop

​Codex (OpenAI)

​Cursor

​Windsurf

​Cline (VS Code)

​Generic / custom agent

​6. Available tools

​create_tunnel arguments

​7. Security notes

​Related pages

MCP server

Claude Code plugin

Load balancing

P2P tunnels

AI tools hub

Agent manual

1. Prerequisites

2. Get an API token (one-time)

3. The two server settings

4. Quick install (any harness)

5. Per-harness configuration

Claude Code

Claude Desktop

Codex (OpenAI)

Cursor

Windsurf

Cline (VS Code)

Generic / custom agent

6. Available tools

`create_tunnel` arguments

7. Security notes

Related pages