tunnel-mcp

name	tunnel-mcp
description	Create, connect, list, and inspect MCP tunnel runtimes through the local tunnel-client plugin. Use when Codex needs to manage secure MCP tunnels with aliases and native tunnel-client runtime processes.

Tunnel MCP

Use scripts/tunnel_mcp from this plugin when a user asks Codex to manage MCP tunnels through tunnel-client. The plugin entrypoint is a thin router onto the public native tunnel-client runtimes ... and tunnel-client admin-profiles ... command trees.

When the tunnel-mcp MCP app tools are available, use them first instead of manual shell routing:

• install_or_select_tunnel_client
• create_tunnel_runtime
• connect_stdio_mcp
• list_runtime_aliases
• runtime_status
• stop_runtime

The app tools are an operator surface over native tunnel-client; they orchestrate tunnel-client runtimes ..., normalize structured output, and keep tunnel protocol/runtime behavior in the Go binary.

Before acting, consult only the smallest relevant reference under references/:

• references/binary.md: how to find or obtain a public-safe tunnel-client binary
• references/setup-and-install.md: install, export, reset, binary-vs-bundle setup
• references/profiles-state-and-keys.md: profiles, state dirs, admin/runtime key split
• references/runtime-flows.md: create, connect, list, status, stop, rm, attach by tunnel id
• references/troubleshooting.md: /healthz, /readyz, /ui, status, logs, stale aliases

Rules

• Use tunnel-client admin tunnels for remote tunnel CRUD. Do not call raw tunnel-service HTTP endpoints from this plugin.
• Route operational actions through tunnel-client runtimes ... and tunnel-client admin-profiles ....
• Use scripts/tunnel_mcp self-check for plugin/binary/router compatibility; it must report secret reference presence without printing secret values.
• Use native tunnel-client run --profile <name> only when the user intentionally wants a foreground daemon attached to the current terminal; do not translate profile files into flags in the plugin layer.
• For a long-lived local runtime managed by Codex, use tunnel-client runtimes connect ...; do not use nohup or disown as the tunnel-client supervision path.
• After runtimes connect, run tunnel-client runtimes status <alias> before reporting success. Only report success when status shows the managed runtime running with health reported; use --json when Codex needs explicit process_running, healthy, and ready fields.
• Do not assume a source checkout, build system, helper, or tmux. The installed plugin must work with the selected tunnel-client binary alone.
• Treat ambient PATH binary candidates as diagnostics unless selected through --tunnel-client-bin, TUNNEL_CLIENT_BIN, or .tunnel-client-bin.
• Tunnel state, admin profiles, generated runtime profiles, stale-alias handling, cleanup classification, and local process management are owned by native tunnel-client; consult the relevant reference before explaining those details.
• Keep admin and runtime credentials split: admin CRUD uses admin-profiles; runtime attach/connect uses --runtime-api-key env:NAME or file:/path. Do not pass literal keys.
• Never write literal API keys, bearer tokens, cookies, or inline sk- style secret material into plugin state or generated configs.
• Surface control_plane_poll_health separately from /healthz and /readyz; local readiness can be green while control-plane polling fails through a dead proxy.