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.