Secure MCP Tunnel Client

https://github.com/openai/tunnel-client
Admin
Secure MCP Tunnel Client is a customer-run agent that connects a private or localhost Model Context...
Tokens:257,973
Snippets:1,687
Trust Score:9.4
License:Apache-2.0
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### tunnel-client help quickstart (installed on PATH)

Source: https://github.com/openai/tunnel-client/blob/master/cmd/client/help_topics/quickstart.txt

Run this command to display the quickstart help when tunnel-client is already installed and available on your PATH.

```shell
tunnel-client help quickstart
```

--------------------------------

### Verify version and start quickstart

Source: https://github.com/openai/tunnel-client/blob/master/README.md

Checks the installed version and launches the guided setup. The Homebrew formula installs the matching tunnel-client, bundled cloudflared, and companion manifest together, exposing only the tunnel-client command.

```bash
tunnel-client --version
```

```bash
tunnel-client help quickstart
```

--------------------------------

### Run the in-memory Go SDK example

Source: https://github.com/openai/tunnel-client/blob/master/examples/go-sdk-inmemory/README.md

Install the Go SDK, set the required environment variables (CONTROL_PLANE_TUNNEL_ID and CONTROL_PLANE_API_KEY), and run the in-memory example.

```bash
go get github.com/openai/tunnel-client
export CONTROL_PLANE_TUNNEL_ID=tunnel_0123456789abcdef0123456789abcdef
export CONTROL_PLANE_API_KEY=sk-...
go run ./examples/go-sdk-inmemory
```

--------------------------------

### Get CLI help for quickstart, doctor, and plugin

Source: https://github.com/openai/tunnel-client/blob/master/docs/end-user-guide.md

Use these commands to let the CLI explain itself before hand-editing configuration. This is the shortest supported binary-first path.

```bash
tunnel-client help quickstart
tunnel-client help doctor
tunnel-client help plugin
```

--------------------------------

### Show quickstart and samples help

Source: https://github.com/openai/tunnel-client/blob/master/docs/onboarding.md

Displays the embedded quickstart and sample help for the tunnel-client CLI.

```bash
tunnel-client help quickstart
tunnel-client help samples
```

--------------------------------

### Binary-first flow: quickstart, profiles, init, doctor, run

Source: https://github.com/openai/tunnel-client/blob/master/README.md

Commands for the shortest supported path from a local MCP server to ChatGPT or Codex. Run `tunnel-client help quickstart` first. Use `tunnel-client init` with a sample profile, then `doctor` to check, and `run` to start the daemon. Note the stdio deployment limit: only one active instance per tunnel ID when using `--mcp.command` / `MCP_COMMAND`.

```bash
tunnel-client help quickstart
tunnel-client profiles samples list
tunnel-client profiles samples show sample_mcp_enterprise_proxy
tunnel-client init --sample sample_mcp_stdio_local --profile local-stdio --tunnel-id tunnel_0123456789abcdef0123456789abcdef --mcp-command "python /path/to/server.py"
tunnel-client doctor --profile local-stdio --explain
tunnel-client run --profile local-stdio
tunnel-client run --profile-file ./profiles/local-stdio.yaml
```

--------------------------------

### tunnel-client quickstart and setup commands

Source: https://github.com/openai/tunnel-client/blob/master/docs/connectors.md

Use these CLI commands to set up and verify a connector profile. The commands create a local-stdio profile, check its health, and run it. Run them in order before hand-editing YAML.

```bash
tunnel-client help quickstart
```

```bash
tunnel-client profiles samples list
```

```bash
tunnel-client init --sample sample_mcp_stdio_local --profile local-stdio --tunnel-id tunnel_0123456789abcdef0123456789abcdef --mcp-command "python /path/to/server.py"
```

```bash
tunnel-client doctor --profile local-stdio --explain
```

```bash
tunnel-client run --profile local-stdio
```

--------------------------------

### Tunnel client quickstart CLI commands

Source: https://github.com/openai/tunnel-client/blob/master/docs/enterprise-customer-onboarding.md

Starts the tunnel client using the supported CLI path. Sets the control plane API key, initializes with a sample profile for a local stdio MCP server, runs doctor checks, and starts the client.

```bash
tunnel-client help quickstart
export CONTROL_PLANE_API_KEY="sk-..."
tunnel-client init \
  --sample sample_mcp_stdio_local \
  --profile local-stdio \
  --tunnel-id tunnel_0123456789abcdef0123456789abcdef \
  --mcp-command "python /path/to/server.py"
tunnel-client doctor --profile local-stdio --explain
tunnel-client run --profile local-stdio
```

--------------------------------

### Build and run tunnel-client help quickstart from source

Source: https://github.com/openai/tunnel-client/blob/master/cmd/client/help_topics/quickstart.txt

Build the tunnel-client binary from a source checkout and display the quickstart help. Requires make and Go toolchain.

```shell
make admin-ui
go build -o bin/tunnel-client ./cmd/client
./bin/tunnel-client help quickstart
```

--------------------------------

### Install tunnel-client via Homebrew and verify version/help

Source: https://github.com/openai/tunnel-client/blob/master/docs/troubleshooting.md

Use the supported Homebrew installation path to avoid macOS Gatekeeper blocking the downloaded archive. Run `tunnel-client --version` and `tunnel-client help quickstart` to verify the installation.

```bash
brew install openai/tools/tunnel-client
tunnel-client --version
tunnel-client help quickstart
```

--------------------------------

### Export and install plugin bundle from binary

Source: https://github.com/openai/tunnel-client/blob/master/plugins/tunnel-mcp/README.md

Exports the plugin bundle to a directory, then runs the install script from that bundle. The install script accepts --tunnel-client-bin to point to the tunnel-client binary.

```bash
tunnel-client codex plugin export --dir /tmp/tunnel-mcp
cd /tmp/tunnel-mcp
sh scripts/install_plugin.sh --tunnel-client-bin /path/to/tunnel-client
```

--------------------------------

### Generate end-user guide output

Source: https://github.com/openai/tunnel-client/blob/master/README.md

Builds the shareable end-user guide locally using Make targets for screenshots, HTML, and slides.

```bash
make end-user-guide-screenshots
```

```bash
make end-user-guide-html
```

```bash
make end-user-guide-slides
```

--------------------------------

### Source-checkout fallback installer (bash)

Source: https://github.com/openai/tunnel-client/blob/master/plugins/tunnel-mcp/README.md

Runs the install script from the source checkout. Use this when the binary is missing but the source is available.

```bash
./plugins/tunnel-mcp/scripts/install_plugin.sh --tunnel-client-bin /path/to/tunnel-client
```

--------------------------------

### Install and manage plugin via tunnel-client binary

Source: https://github.com/openai/tunnel-client/blob/master/plugins/tunnel-mcp/README.md

Use these commands when a tunnel-client binary is already available. They install, check status, diagnose, and uninstall the plugin bundle, ensuring the installed bundle matches the binary version.

```bash
tunnel-client codex plugin install
tunnel-client codex status
tunnel-client codex diagnose --json
tunnel-client codex plugin uninstall
```

--------------------------------

### Exported bundle install commands

Source: https://github.com/openai/tunnel-client/blob/master/plugins/tunnel-mcp/skills/tunnel-mcp/references/setup-and-install.md

Use these commands when the binary is not installed or you need to inspect the plugin contents first. They export the plugin bundle and run the install script for Unix or PowerShell.

```shell
tunnel-client codex plugin export --dir /tmp/tunnel-mcp
```

```shell
cd /tmp/tunnel-mcp && sh scripts/install_plugin.sh --tunnel-client-bin /path/to/tunnel-client
```

```powershell
Set-Location C:\tmp\tunnel-mcp; powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\Install-Plugin.ps1 --tunnel-client-bin C:\path\to\tunnel-client.exe
```

--------------------------------

### Binary-owned install commands

Source: https://github.com/openai/tunnel-client/blob/master/plugins/tunnel-mcp/skills/tunnel-mcp/references/setup-and-install.md

Use these commands when a tunnel-client binary is available. They install, uninstall, check status, and diagnose the plugin.

```shell
tunnel-client codex plugin install
```

```shell
tunnel-client codex plugin uninstall
```

```shell
tunnel-client codex status
```

```shell
tunnel-client codex diagnose --json
```

--------------------------------

### Run adminui in dev mode with proxy

Source: https://github.com/openai/tunnel-client/blob/master/adminui/README.md

Install dependencies and start the Vite dev server from the adminui directory. The dev server proxies API/health/metrics requests to http://127.0.0.1:8080 by default.

```bash
cd adminui
pnpm install --frozen-lockfile --config.shared-workspace-lockfile=false --config.confirmModulesPurge=false
pnpm dev
```

--------------------------------

### Install and use the Codex plugin from the tunnel-client binary

Source: https://github.com/openai/tunnel-client/blob/master/docs/onboarding.md

Run these commands to install the Codex plugin and interact with it. The commands cover assistant, status, plugin install, runtimes list, and plugin uninstall.

```bash
tunnel-client codex assistant "Summarize what tunnel-client is for."
tunnel-client codex status
tunnel-client codex plugin install
tunnel-client runtimes list
tunnel-client codex plugin uninstall
```

--------------------------------

### Install tunnel-client with Homebrew

Source: https://github.com/openai/tunnel-client/blob/master/README.md

Installs the tunnel-client from the official OpenAI tap. Use this instead of manually downloaded release ZIPs, which are not notarized and may be blocked by Gatekeeper.

```bash
brew install openai/tools/tunnel-client
```

--------------------------------

### Enable and start tunnel-client service

Source: https://github.com/openai/tunnel-client/blob/master/docs/deployment/systemd-vm.md

Run these commands to reload systemd, enable the service to start on boot, and check its status. The commands assume the unit file has been created at /etc/systemd/system/tunnel-client.service.

```bash
sudo systemctl daemon-reload
sudo systemctl enable --now tunnel-client
sudo systemctl status tunnel-client
```

--------------------------------

### tunnel-client help commands

Source: https://github.com/openai/tunnel-client/blob/master/docs/configuration.md

Use the CLI as the first discovery surface for quickstart, samples, doctor, oauth, and plugin help.

```bash
tunnel-client help quickstart
```

```bash
tunnel-client help samples
```

```bash
tunnel-client help doctor
```

```bash
tunnel-client help oauth
```

```bash
tunnel-client help plugin
```

--------------------------------

### Source-checkout fallback installer (PowerShell)

Source: https://github.com/openai/tunnel-client/blob/master/plugins/tunnel-mcp/README.md

Runs the PowerShell install script from the source checkout on Windows.

```powershell
.\plugins\tunnel-mcp\scripts\Install-Plugin.ps1 --tunnel-client-bin C:\path\to\tunnel-client.exe
```

--------------------------------

### Starter prompts for Codex

Source: https://github.com/openai/tunnel-client/blob/master/docs/configuration.md

Use these prompts to guide Codex through common tunnel-client tasks, from discovery to running the daemon.

```text
Figure out what tunnel-client is for from the binary help, then get me to /ui with the shortest local path.
```

```text
Use tunnel-client to create or reuse a profile, run doctor --explain, and then start the daemon.
```

```text
Install the Codex plugin from the tunnel-client binary, connect the provided tunnel id, and tell me whether the runtime is launched, healthy, or ready.
```

```text
Use tunnel-client runtimes to attach a local MCP server to an existing tunnel id and report the ui_url.
```

--------------------------------

### Run embedded demo MCP server and initialize with DCR

Source: https://github.com/openai/tunnel-client/blob/master/docs/onboarding.md

Starts the embedded demo MCP server, then initializes a profile pointing to it for end-to-end validation.

```bash
tunnel-client dev mcp-stub
tunnel-client init --sample sample_mcp_with_dcr --profile sample_mcp_with_dcr --tunnel-id tunnel_... --mcp-server-url http://127.0.0.1:NNNN/mcp
```

--------------------------------

### Loaded profile path example

Source: https://github.com/openai/tunnel-client/blob/master/docs/configuration.md

Shows the default XDG fallback path for the named profile command above.

```text
~/.config/tunnel-client/sample_mcp_with_dcr.yaml
```

--------------------------------

### Verify plugin installation and status

Source: https://github.com/openai/tunnel-client/blob/master/plugins/tunnel-mcp/README.md

Checks that the plugin bundle is installed, the config.toml has the plugin entry, the helper script runs, and the plugin status and diagnostics are healthy. Also runs a self-check.

```bash
CODEX_HOME_DIR="${CODEX_HOME:-$HOME/.codex}"
test -f "$CODEX_HOME_DIR/plugins/cache/debug/tunnel-mcp/local/.codex-plugin/plugin.json"
grep -A2 '^\[plugins\."tunnel-mcp@debug"\]' "$CODEX_HOME_DIR/config.toml"
"$CODEX_HOME_DIR/plugins/cache/debug/tunnel-mcp/local/scripts/tunnel_mcp" --help
tunnel-client codex status --json
tunnel-client codex diagnose --json
scripts/tunnel_mcp self-check
```

--------------------------------

### Install plugin bundle from exported bundle in Windows PowerShell

Source: https://github.com/openai/tunnel-client/blob/master/plugins/tunnel-mcp/README.md

For Windows PowerShell, navigate to the exported bundle root and run the PowerShell install script with the --tunnel-client-bin parameter.

```powershell
Set-Location C:\tmp\tunnel-mcp
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\Install-Plugin.ps1 --tunnel-client-bin C:\path\to\tunnel-client.exe
```

--------------------------------

### Common tunnel-client runtime flows

Source: https://github.com/openai/tunnel-client/blob/master/plugins/tunnel-mcp/README.md

Shows typical admin profile setup, runtime creation, connection, and status/stop/removal commands.

```bash
tunnel-client admin-profiles set sandbox \
  --admin-key env:SANDBOX_OPENAI_ADMIN_KEY \
  --control-plane-base-url https://api.openai.com

tunnel-client runtimes create \
  --alias awesome-mcp \
  --name "Awesome MCP" \
  --admin-profile sandbox \
  --organization-id org_123

tunnel-client runtimes connect \
  --alias awesome-mcp \
  --admin-profile sandbox \
  --organization-id org_123 \
  --mcp-server-url http://127.0.0.1:3001/mcp

tunnel-client runtimes connect \
  --alias existing-mcp \
  --tunnel-id tunnel_0123456789abcdef0123456789abcdef \
  --runtime-api-key env:TUNNEL_RUNTIME_KEY \
  --mcp-command "python /path/to/server.py"

tunnel-client runtimes status awesome-mcp
tunnel-client runtimes stop awesome-mcp
tunnel-client runtimes rm awesome-mcp
```

--------------------------------

### Validate and start tunnel-client

Source: https://github.com/openai/tunnel-client/blob/master/cmd/client/help_topics/quickstart.txt

Runs doctor to validate the profile and then starts the tunnel-client daemon with that profile. Replace <name> with your profile name.

```shell
tunnel-client doctor --profile <name> --explain
tunnel-client run --profile <name>
```

--------------------------------

### Run minimal end-to-end demo with health checks

Source: https://github.com/openai/tunnel-client/blob/master/docs/end-user-guide.md

Use this when you already have a tunnel ID and want the smallest end-to-end demo. It starts the daemon with an embedded MCP stub, writes the health URL to a file, then checks /readyz and opens the /ui dashboard.

```bash
export CONTROL_PLANE_API_KEY="sk-..."
health_url_file="$(mktemp "${TMPDIR:-/tmp}/tunnel-client-health.XXXXXX.url")"
tunnel-client run \
  --embedded-mcp-stub \
  --control-plane.tunnel-id tunnel_0123456789abcdef0123456789abcdef \
  --health.listen-addr 127.0.0.1:0 \
  --health.url-file "$health_url_file"
curl -fsS "$(cat "$health_url_file")/readyz"
open "$(cat "$health_url_file")/ui"
```

--------------------------------

### Run full client with managed Cloudflare provisioning

Source: https://github.com/openai/tunnel-client/blob/master/README.md

Run the full tunnel-client binary with managed Cloudflare provisioning. The authenticated client fetches the runtime token and starts the companion without distributing a static token.

```bash
tunnel-client run \
  --cloudflared.managed \
  --control-plane.tunnel-id tunnel_0123456789abcdef0123456789abcdef \
  --mcp.server-url https://mcp.example.com/mcp
```

--------------------------------

### Build tunnel-client from source (macOS/Linux)

Source: https://github.com/openai/tunnel-client/blob/master/plugins/tunnel-mcp/skills/tunnel-mcp/references/binary.md

Use these commands to clone the public repository and build the tunnel-client binary on macOS or Linux. The build outputs to bin/tunnel-client. Only run when the user explicitly asks to set up or install the binary.

```bash
git clone https://github.com/openai/tunnel-client.git
cd tunnel-client
go build -o bin/tunnel-client ./cmd/client
```

--------------------------------

### Install Codex plugin and manage runtimes

Source: https://github.com/openai/tunnel-client/blob/master/docs/onboarding.md

Commands to install, uninstall, and inspect the Codex plugin, plus list runtimes. Use the native runtimes command family for lifecycle operations.

```bash
tunnel-client codex plugin install
tunnel-client help plugin
tunnel-client runtimes list
tunnel-client codex plugin uninstall
```

--------------------------------

### Build tunnel-client from source (Windows PowerShell)

Source: https://github.com/openai/tunnel-client/blob/master/plugins/tunnel-mcp/skills/tunnel-mcp/references/binary.md

Use these commands to clone the public repository and build the tunnel-client.exe binary on Windows. The build outputs to bin/tunnel-client.exe. Only run when the user explicitly asks to set up or install the binary.

```powershell
git clone https://github.com/openai/tunnel-client.git
cd tunnel-client
go build -o bin/tunnel-client.exe ./cmd/client
```

--------------------------------

### Add tunnel-client Go module

Source: https://github.com/openai/tunnel-client/blob/master/README.md

Installs the tunnel-client module as a Go dependency.

```bash
go get github.com/openai/tunnel-client
```

--------------------------------

### Capabilities header parsing example

Source: https://github.com/openai/tunnel-client/blob/master/docs/protocol.md

Two field lines with the same set semantics as 'wrong-cluster-v1, example-future-v1'. The example name is illustrative and not implemented.

```http
X-Tunnel-Client-Capabilities: wrong-cluster-v1, example-future-v1
X-Tunnel-Client-Capabilities: , wrong-cluster-v1
```

--------------------------------

### Initialize HTTP MCP server with OAuth/DCR metadata

Source: https://github.com/openai/tunnel-client/blob/master/cmd/client/help_topics/quickstart.txt

Starts a local MCP stub for development and initializes a profile for an HTTP MCP server with OAuth/DCR metadata, or to exercise the full contract. Replace NNNN with the actual port from the dev command output.

```shell
tunnel-client dev mcp-stub
tunnel-client init --sample sample_mcp_with_dcr --profile sample_mcp_with_dcr --tunnel-id tunnel_... --mcp-server-url http://127.0.0.1:NNNN/mcp
```

--------------------------------

### Verify complete release evidence set with gh release download and verifiers

Source: https://github.com/openai/tunnel-client/blob/master/README.md

Downloads every release asset into a clean directory and runs both fail-closed contract verifiers: verify_release_provenance.sh and verify_release_evidence.sh. Requires the variables from the previous example (release, bundle, source_digest).

```bash
mkdir release-evidence
gh release download "${release}" \
  --repo openai/tunnel-client \
  --dir release-evidence

./scripts/verify_release_provenance.sh \
  --bundle "release-evidence/${bundle}" \
  --artifact-dir release-evidence \
  --release "${release}" \
  --source-digest "${source_digest}"
./scripts/verify_release_evidence.sh \
  --artifact-dir release-evidence \
  --release "${release}" \
  --source-digest "${source_digest}"
```

--------------------------------

### Verify persisted .tunnel-client-bin hint

Source: https://github.com/openai/tunnel-client/blob/master/plugins/tunnel-mcp/skills/tunnel-mcp/references/setup-and-install.md

After install or export, verify the persisted .tunnel-client-bin hint before using the router. The first command checks the file exists; the second runs a self-check.

```shell
test -f "$CODEX_HOME/plugins/cache/<marketplace>/tunnel-mcp/<version>/.tunnel-client-bin"
```

```shell
scripts/tunnel_mcp self-check
```

--------------------------------

### GET /readyz

Source: https://github.com/openai/tunnel-client/blob/master/docs/enterprise-customer-onboarding.md

Readiness check endpoint for the tunnel client. Returns a success response if the client is ready to accept traffic.

```APIDOC
## [GET] /readyz

### Description
Readiness check endpoint for the tunnel client. Returns a success response if the client is ready to accept traffic.

### Method
GET

### Endpoint
http://127.0.0.1:8080/readyz

### Response
#### Success Response (200)
- No content or simple success indicator

#### Response Example
(No explicit response body documented)
```

--------------------------------

### Native CLI runtime operations

Source: https://github.com/openai/tunnel-client/blob/master/plugins/tunnel-mcp/skills/tunnel-mcp/references/setup-and-install.md

Use the native CLI for runtime operations after install. The plugin is a thin router and does not own protocol logic.

```shell
tunnel-client runtimes create ...
```

```shell
tunnel-client runtimes connect ...
```

```shell
tunnel-client runtimes list
```

```shell
tunnel-client runtimes cleanup
```

```shell
tunnel-client admin-profiles list
```

--------------------------------

### Run embedded demo tools with tunnel-client

Source: https://github.com/openai/tunnel-client/blob/master/README.md

Starts the built-in server_info, echo, and uppercase tools using stateless MCP handling. Requires CONTROL_PLANE_API_KEY and CONTROL_PLANE_TUNNEL_ID environment variables. The --embedded-stateless-mcp-stub flag issues no MCP session ID and does not require session affinity.

```bash
export CONTROL_PLANE_API_KEY="sk-..."
export CONTROL_PLANE_TUNNEL_ID="tunnel_0123456789abcdef0123456789abcdef"
tunnel-client run --embedded-stateless-mcp-stub --health.listen-addr 127.0.0.1:0
```

--------------------------------

### GET /

Source: https://github.com/openai/tunnel-client/blob/master/docs/configuration.md

Serves the embedded web UI. This endpoint is available when running `tunnel-client run` and provides the main UI entrypoint.

```APIDOC
## GET /

### Description
Serves the embedded web UI. This endpoint is available when running `tunnel-client run` and provides the main UI entrypoint.

### Method
GET

### Endpoint
/

### Response
#### Success Response (200)
- HTML content for the web UI

#### Response Example
```html
<!DOCTYPE html>
<html>...</html>
```
```

--------------------------------

### GET /readyz

Source: https://github.com/openai/tunnel-client/blob/master/docs/health.md

Returns the readiness decision. Returns 200 when ready and 503 while gated.

```APIDOC
## [GET] /readyz

### Description
Returns the readiness decision. Returns 200 when ready and 503 while gated.

### Method
GET

### Endpoint
/readyz

### Response
#### Success Response (200)
- **body** (string) - Readiness response when ready.

#### Error Response (503)
- **body** (string) - Readiness response while gated.
```

--------------------------------

### GET /ui

Source: https://github.com/openai/tunnel-client/blob/master/docs/configuration.md

Serves the embedded web UI. This endpoint is available when running `tunnel-client run` and provides the main UI entrypoint.

```APIDOC
## GET /ui

### Description
Serves the embedded web UI. This endpoint is available when running `tunnel-client run` and provides the main UI entrypoint.

### Method
GET

### Endpoint
/ui

### Response
#### Success Response (200)
- HTML content for the web UI

#### Response Example
```html
<!DOCTYPE html>
<html>...</html>
```
```

--------------------------------

### Example Deployment manifest for tunnel-client

Source: https://github.com/openai/tunnel-client/blob/master/docs/deployment/kubernetes-dedicated.md

Deploys tunnel-client with 5 replicas, health probes on /healthz and /readyz, and environment variables for CONTROL_PLANE_TUNNEL_ID, MCP_SERVER_URL, HEALTH_LISTEN_ADDR, and CONTROL_PLANE_API_KEY from a secret. The MCP_SERVER_URL target must be stateless, share session state, or be sticky-aware. Replace the v1.2.3 image tag with a released version or digest.

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: tunnel-client
spec:
  replicas: 5
  selector:
    matchLabels: { app: tunnel-client }
  template:
    metadata:
      labels: { app: tunnel-client }
    spec:
      containers:
        - name: tunnel-client
          image: ghcr.io/openai/tunnel-client:v1.2.3
          env:
            - name: CONTROL_PLANE_TUNNEL_ID
              value: tunnel_0123456789abcdef0123456789abcdef
            - name: MCP_SERVER_URL
              # This Service must be stateless, share MCP session state, or keep
              # MCP sessions sticky to the correct backend.
              value: http://mcp-server.default.svc.cluster.local:3000/mcp
            - name: HEALTH_LISTEN_ADDR
              value: ":8080"
            - name: CONTROL_PLANE_API_KEY
              valueFrom:
                secretKeyRef:
                  name: openai-api-key
                  key: api_key
          ports:
            - name: health
              containerPort: 8080
          livenessProbe:
            httpGet: { path: /healthz, port: health }
            initialDelaySeconds: 5
          readinessProbe:
            httpGet: { path: /readyz, port: health }
            initialDelaySeconds: 5
```

--------------------------------

### Run tunnel-client with templates.yaml

Source: https://github.com/openai/tunnel-client/blob/master/docs/harpoon-target-templates.md

Starts the client with the secrets already present in its environment. Subscribes only to the Harpoon channel; add MCP bindings and set poll_channels to [main, harpoon] to serve an existing MCP server.

```sh
tunnel-client run --config templates.yaml

```

--------------------------------

### Arguments with headers and execution limits

Source: https://github.com/openai/tunnel-client/blob/master/docs/harpoon-target-templates.md

Example arguments object for a target that accepts caller headers. Only header names explicitly listed in the target's header_rules or allowed_headers are permitted; timeout_ms and max_response_bytes are optional bounded execution limits.

```json
{
  "label": "get_profile",
  "parameters": {"session_id": "session-123"},
  "headers": {"Accept": "application/json", "X-Request-Tag": "support-check"},
  "timeout_ms": 10000,
  "max_response_bytes": 32768
}
```

--------------------------------

### Complete ChatGPT setup prompt for Codex

Source: https://github.com/openai/tunnel-client/blob/master/README.md

Paste this prompt into Codex on a machine with browser access and a terminal that can reach your private MCP server. It walks through setting up and verifying a private Secure MCP Tunnel from an internal MCP server to ChatGPT, including permissions, doctor, and a final ChatGPT tool call.

```text
Help me set up and verify a private Secure MCP Tunnel from my internal MCP server to ChatGPT end to end. Use browser/computer access and a terminal, following https://developers.openai.com/api/docs/guides/secure-mcp-tunnels and https://github.com/openai/tunnel-client/blob/master/docs/onboarding.md; check current UI and CLI help as you go.

First identify the intended Platform organization and ChatGPT workspace, MCP server HTTP URL or stdio command, and client host. Inspect existing tunnel, key, and ChatGPT custom MCP plugin; reuse suitable resources. Confirm tunnel organization/workspace association and permissions: tunnel creators need Tunnels Read + Manage; the restricted runtime key and plugin operator need Tunnels Read + Use. Keep literal secrets out of chat, command arguments, logs, screenshots, and config files; have me enter them locally through a secure input or environment reference.

Install the supported tunnel-client; run `tunnel-client help quickstart`, configure the server, run `tunnel-client doctor --profile <name> --explain`, start the client, and verify readiness and active polling. Keep it running for discovery and calls. In ChatGPT Plugins, add or finish a private custom MCP server with Connection: Tunnel, select the same tunnel, configure required authentication, install it, and make a safe representative tool call.

Report observed evidence for each checkpoint and the exact error and next action for any blocker. Call setup complete only after the ChatGPT tool call succeeds.
```

--------------------------------

### List and show sample profiles

Source: https://github.com/openai/tunnel-client/blob/master/docs/configuration.md

Use these commands to list available sample profiles and show details for a specific sample.

```bash
tunnel-client profiles samples list
```

```bash
tunnel-client profiles samples show sample_mcp_with_dcr
```

--------------------------------

### Run container with environment variables

Source: https://github.com/openai/tunnel-client/blob/master/docs/deployment/docker.md

Runs the container with required environment variables and port mapping. Replace the example values with your own. The health listener defaults to 127.0.0.1:8080; set HEALTH_LISTEN_ADDR=:8080 only when publishing to a trusted network.

```bash
docker run --rm \
  -e CONTROL_PLANE_API_KEY="sk-..." \
  -e CONTROL_PLANE_TUNNEL_ID="tunnel_0123456789abcdef0123456789abcdef" \
  -e MCP_SERVER_URL="https://mcp.internal.example.com/mcp" \
  -e LOG_LEVEL="info" \
  -e LOG_FORMAT="json" \
  -e HEALTH_LISTEN_ADDR=":8080" \
  -p 8080:8080 \
  ghcr.io/openai/tunnel-client:v1.2.3
```

--------------------------------

### Full YAML config example

Source: https://github.com/openai/tunnel-client/blob/master/docs/configuration.md

Complete YAML configuration for tunnel-client. Secret-bearing fields should use env:VARNAME or file:/path/to/secret; literal values are accepted for compatibility but not recommended. The env: and file: prefixes are reserved for these references.

```yaml
config_version: 1
# Optional. Forward the original HTTP X-Request-Id to MCP HTTP targets (default).
# Use [mcp, harpoon, oauth] to opt in Harpoon REST and queued OAuth discovery
# at the configured MCP origin, or none to disable automatic forwarding.
forward_request_id: mcp
control_plane:
  base_url: https://api.openai.com # citadel-ignore: public endpoint example for external tunnel-client config
  # Optional path appended before tunnel-client adds its /v1/... routes.
  url_path: /chatgpttunnelgateway/dev/us
  tunnel_id: tunnel_0123456789abcdef0123456789abcdef
  api_key: env:CONTROL_PLANE_API_KEY
  # Optional. When configured with the default api.openai.com base URL,
  # tunnel-client automatically uses https://mtls.api.openai.com.
  client_cert: file:/run/secrets/control-plane-client.crt
  client_key: file:/run/secrets/control-plane-client.key
  max_inflight_requests: 20
  poll_timeout: 30000ms
  poll_deadline_guardrail: 5000ms
  extra_headers:
    X-Debug-Mode: "1"
    X-Internal-Auth: env:CONTROL_PLANE_HEADER_VALUE
log:
  level: info
  format: json
  file: /var/log/tunnel-client/tunnel-client.ndjson
health:
  listen_addr: 127.0.0.1:8080
  url_file: /run/tunnel-client/health-url
admin_ui:
  open_browser: false
  log_buffer_events: 2000
process:
  pid_file: /run/tunnel-client/tunnel-client.pid
cloudflared:
  # Optional. Fetch the managed runtime token from tunnel-service on startup.
  managed: true
  # Optional static override. Use an env: or file: reference; literal tokens are rejected.
  # When present, this takes precedence over managed fetch.
  token: env:CLOUDFLARED_TOKEN
  # Optional source-build/test override. Release archives discover the sibling binary.
  path: /opt/tunnel-client/cloudflared
  ready_timeout: 30s
mcp:
  server_urls:
    - channel: main
      url: https://mcp.example.com/mcp
      # Optional. Dial the logical HTTP URL over a local Unix socket instead of TCP.
      unix_socket: env:MCP_UNIX_SOCKET_PATH
  commands:
    - channel: tools
      command: python -m tools_mcp
  extra_headers:
    X-Internal-Auth: env:MCP_RUNTIME_HEADER_VALUE
  discovery_extra_headers:
    X-Discovery-Auth: file:/run/secrets/mcp-discovery-header
  # Optional. Explicitly trust separate OAuth metadata/authorization origins.
  oauth_trusted_origins:
    - https://auth.example.com
  # Optional. Wait for a sidecar/local HTTP listener before the first poll.
  startup_wait_timeout: 60s
  connection_max_ttl: 10m
  max_concurrent_requests: 10
harpoon:
  targets:
    - label: auth
      url: https://auth.example.com
      description: Auth server
  additional_transports:
    - http-streamable
proxy:
  check_interval: 60s
```

--------------------------------

### Template with multiple parameters and call arguments

Source: https://github.com/openai/tunnel-client/blob/master/docs/harpoon-target-templates.md

Defines a GET template with two path arguments, two dynamic query values, and one fixed query value, then shows the matching call arguments. All four parameters are required and validated before any outbound request is sent.

```yaml
- label: get_tenant_case
  description: Get one tenant case with an approved view
  template:
    version: 1
    origin: https://cases.example
    method: GET
    path_template: /tenants/{tenant_id}/cases/{case_id}
    query:
      view: "{view}"
      requestId: "{request_id}"
      archive: "false"
    parameters:
      tenant_id:
        type: string
        required: true
        pattern: '^[A-Za-z0-9_-]+$'
        max_length: 64
      case_id:
        type: string
        required: true
        pattern: '^[A-Za-z0-9_-]+$'
        max_length: 64
      view:
        type: string
        required: true
        enum: [summary, details]
        max_length: 7
      request_id:
        type: string
        required: true
        pattern: '^[A-Za-z0-9_-]+$'
        max_length: 64
    headers:
      Authorization: env:CASE_API_AUTHORIZATION
    follow_redirects: false
```

```json
{
  "label": "get_tenant_case",
  "parameters": {
    "tenant_id": "tenant-1",
    "case_id": "CASE-123",
    "view": "summary",
    "request_id": "req-456"
  }
}
```

--------------------------------

### Create systemd unit file for tunnel-client

Source: https://github.com/openai/tunnel-client/blob/master/docs/deployment/systemd-vm.md

Use this systemd unit to run tunnel-client as a service. It sets the working directory, starts the client with logging flags, and configures environment variables for the tunnel ID, MCP server URL, API key, and health check address. The service is set to restart always with a 2-second delay.

```ini
[Unit]
Description=OpenAI tunnel client
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
WorkingDirectory=/opt/tunnel-client
ExecStart=/opt/tunnel-client/tunnel-client run --log.level=info --log.format=json
Restart=always
RestartSec=2

# Prefer an EnvironmentFile or a secrets manager; shown inline for clarity.
Environment=CONTROL_PLANE_TUNNEL_ID=tunnel_0123456789abcdef0123456789abcdef
Environment=MCP_SERVER_URL=https://mcp.internal.example.com/mcp
Environment=CONTROL_PLANE_API_KEY=sk-...
Environment=HEALTH_LISTEN_ADDR=127.0.0.1:8080

[Install]
WantedBy=multi-user.target
```

--------------------------------

### Initialize and run with a named profile

Source: https://github.com/openai/tunnel-client/blob/master/docs/onboarding.md

Creates a local-stdio profile from a sample, runs doctor with explanation, then runs the daemon using that profile.

```bash
tunnel-client init --sample sample_mcp_stdio_local --profile local-stdio --tunnel-id tunnel_0123456789abcdef0123456789abcdef --mcp-command "python /path/to/server.py"
tunnel-client doctor --profile local-stdio --explain
tunnel-client run --profile local-stdio
```

--------------------------------

### Docker run command with environment variables

Source: https://github.com/openai/tunnel-client/blob/master/docs/enterprise-customer-onboarding.md

Run the tunnel client in Docker with required and recommended environment variables. The example uses an illustrative v1.2.3 tag; replace it with a released version or digest. Exposes health endpoint on port 8080.

```bash
docker run --rm \
  -e CONTROL_PLANE_API_KEY="sk-..." \
  -e CONTROL_PLANE_TUNNEL_ID="<tunnel_id>" \
  -e CONTROL_PLANE_BASE_URL="<CONTROL_PLANE_BASE_URL>" \
  -e MCP_SERVER_URL="https://mcp.internal.example.com/mcp" \
  -e LOG_LEVEL="info" \
  -e LOG_FORMAT="json" \
  -e HEALTH_LISTEN_ADDR=":8080" \
  -p 8080:8080 \
  ghcr.io/openai/tunnel-client:v1.2.3
```

--------------------------------

### Run tunnel-client in foreground with logging flags

Source: https://github.com/openai/tunnel-client/blob/master/docs/onboarding.md

Starts the daemon in the foreground for manual operation. Keep the terminal attached while the daemon runs; for a long-lived runtime that survives the shell, use `tunnel-client runtimes connect ...` instead of `nohup` or `disown`. The process polls the OpenAI tunnel service, forwards JSON-RPC requests to your MCP server, and exposes health endpoints on `HEALTH_LISTEN_ADDR` (default `127.0.0.1:8080`).

```bash
./bin/tunnel-client run --log.level=info --log.format=struct-text
```

--------------------------------

### Initialize with outbound proxy or private PKI

Source: https://github.com/openai/tunnel-client/blob/master/docs/onboarding.md

Sets HTTPS_PROXY and ENTERPRISE_CA_BUNDLE environment variables, then initializes a profile for an enterprise proxy environment.

```bash
export HTTPS_PROXY="http://proxy.internal.example.com:8080"
export ENTERPRISE_CA_BUNDLE="/etc/ssl/certs/proxy-root.pem"
tunnel-client init --sample sample_mcp_enterprise_proxy --profile corp-proxy --tunnel-id tunnel_... --mcp-server-url https://mcp.internal.example.com/mcp
```

--------------------------------

### Prepare post-release development version

Source: https://github.com/openai/tunnel-client/blob/master/docs/development.md

After verifying a stable release and completing its Homebrew handoff, prepare a reviewed source change for the next owner-selected development version, for example `1.2.4-dev` after `1.2.3`. This changes `pkg/version/VERSION` and does not require a Git development tag.

```bash
#!/bin/bash
make release-source-version VERSION=1.2.4-dev
```

--------------------------------

### Manage tunnels with tunnel-client admin commands

Source: https://github.com/openai/tunnel-client/blob/master/docs/enterprise-customer-onboarding.md

Use these CLI commands to create, list, get, update, and delete tunnels. Requires an admin key and at least one scope flag (--organization-id or --workspace-id). After create, wait 25-30 seconds for the tunnel to be active. Delete requires --confirm.

```bash
# Create (requires at least one org/workspace id)
bin/tunnel-client admin tunnels create \
  --name "BigCo Prod MCP Tunnel" \
  --description "Routes BigCo connector traffic to the on-prem MCP server" \
  --workspace-id "<WORKSPACE_ID>"
```

```bash
# After create succeeds, wait 25-30 seconds before expecting the tunnel to be active and ready.
```

```bash
# List by workspace (exactly one filter required: org OR workspace OR tenant)
bin/tunnel-client admin tunnels list --workspace-id "<WORKSPACE_ID>" --json
```

```bash
# Get by id
bin/tunnel-client admin tunnels get "<tunnel_id>"
```

```bash
# Update (PUT-like replacement for org/workspace lists when flags are present)
bin/tunnel-client admin tunnels update "<tunnel_id>" \
  --name "Renamed Tunnel" \
  --organization-id "<ORG_ID>"
```

```bash
# Delete (requires --confirm)
bin/tunnel-client admin tunnels delete "<tunnel_id>" --confirm
```

--------------------------------

### Run single-client local load benchmark

Source: https://github.com/openai/tunnel-client/blob/master/docs/development.md

Runs an opt-in benchmark that starts one real tunnel-client runtime, a loopback local control plane, and a lightweight local MCP server. It warms up one MCP session, then measures concurrent tools/call requests through the full local ingress, polling, dispatch, MCP, and response path. Reports requests per second and p50/p95/p99/max request latency. Adjust the environment variables to explore a laptop's capacity.

```bash
TUNNEL_CLIENT_LOAD_WORKERS=64 \
TUNNEL_CLIENT_LOAD_MAX_INFLIGHT=256 \
TUNNEL_CLIENT_LOAD_MCP_CONCURRENCY=64 \
TUNNEL_CLIENT_LOAD_PAYLOAD_BYTES=1024 \
go test ./e2e -run '^$' -bench '^BenchmarkSingleTunnelClient$' -benchtime=30s -count=1 -benchmem
```

--------------------------------

### Run tunnel-client with embedded MCP stub and open UI

Source: https://github.com/openai/tunnel-client/blob/master/docs/onboarding.md

Recommended binary-first path: creates a temp health URL file, runs the daemon with the stateful MCP stub, checks readiness, and opens the UI.

```bash
health_url_file="$(mktemp "${TMPDIR:-/tmp}/tunnel-client-health.XXXXXX.url")"
tunnel-client run --embedded-mcp-stub --control-plane.tunnel-id tunnel_0123456789abcdef0123456789abcdef --health.listen-addr 127.0.0.1:0 --health.url-file "$health_url_file"
curl -fsS "$(cat "$health_url_file")/readyz"
open "$(cat "$health_url_file")/ui"
```

--------------------------------

### JSON-RPC request body example

Source: https://github.com/openai/tunnel-client/blob/master/docs/enterprise-customer-onboarding.md

Example format of the JSON-RPC object sent by connectors. The connector sends a single JSON-RPC object per request with method POST to /v1/mcp/{tunnel_id}.

```json
{ "jsonrpc":"2.0", "id":1, "method":"tools/call", "params":{ "name":"...", "arguments":{} } }
```

--------------------------------

### Inspect reviewed pin without starting child process

Source: https://github.com/openai/tunnel-client/blob/master/docs/deployment/cloudflared.md

Use the cloudflared version subcommand to inspect the reviewed pin without starting a child process.

```bash
tunnel-client cloudflared version
```

--------------------------------

### Initialize and run a named profile

Source: https://github.com/openai/tunnel-client/blob/master/docs/end-user-guide.md

Use this to set up a named profile instead of the one-command demo path. It creates a profile, runs doctor to explain the configuration, and then runs the tunnel with that profile.

```bash
tunnel-client init \
  --sample sample_mcp_stdio_local \
  --profile local-stdio \
  --tunnel-id tunnel_0123456789abcdef0123456789abcdef \
  --mcp-command "python /path/to/server.py"
tunnel-client doctor --profile local-stdio --explain
tunnel-client run --profile local-stdio
```

--------------------------------

### JSON-RPC result response example

Source: https://github.com/openai/tunnel-client/blob/master/docs/protocol.md

Example of a terminal JSON-RPC response (`resp_type: "jsonrpc_response"`) with a result payload. `request_id` is required, `channel` is optional, and `resp_headers` may include protocol-relevant headers after the allowlist is applied.

```json
{
  "request_id": "req_123",
  "channel": "main",
  "resp_json": {
    "jsonrpc": "2.0",
    "id": "rpc_123",
    "result": {
      "tools": []
    }
  },
  "resp_headers": {
    "Content-Type": ["application/json"]
  },
  "resp_code": 200,
  "resp_type": "jsonrpc_response"
}
```

--------------------------------

### tunnel-client admin tunnels get

Source: https://github.com/openai/tunnel-client/blob/master/docs/enterprise-customer-onboarding.md

Retrieves a tunnel by ID using the CLI helper.

```APIDOC
## tunnel-client admin tunnels get

### Description
Retrieves a tunnel by ID using the CLI helper.

### Method
CLI

### Endpoint
bin/tunnel-client admin tunnels get "<tunnel_id>"

### Parameters
#### Arguments
- **tunnel_id** (string) - Required - The ID of the tunnel to retrieve.

### Request Example
```bash
bin/tunnel-client admin tunnels get "<tunnel_id>"
```

### Response
#### Success Response
Returns the tunnel metadata.
```

--------------------------------

### GET /metrics

Source: https://github.com/openai/tunnel-client/blob/master/docs/health.md

Returns Prometheus metrics for the service.

```APIDOC
## [GET] /metrics

### Description
Returns Prometheus metrics for the service.

### Method
GET

### Endpoint
/metrics

### Response
#### Success Response (200)
- **body** (string) - Prometheus metrics in text format.
```

--------------------------------

### GET /readyz

Source: https://github.com/openai/tunnel-client/blob/master/docs/health.md

Reads a readiness probe for the tunnel client.

```APIDOC
## [GET] /readyz

### Description
Reads a readiness probe for the tunnel client.

### Method
GET

### Endpoint
/readyz

### Request Example
```sh
curl -i 'http://127.0.0.1:8080/readyz'
```

### Response
#### Success Response (200)
- **schema_version** (integer) - Schema version of the response.
- **live** (boolean) - Indicates the process is live.
- **ready** (boolean) - Indicates the process is ready.
- **snapshot_at** (string) - Timestamp of the snapshot (UTC RFC 3339).
- **runtime** (object) - Runtime information.
  - **instance_id** (string) - Unique instance identifier.
  - **version** (string) - Client version.
  - **flavor** (string) - Flavor of the binary (e.g., full).
  - **started_at** (string) - Start timestamp (UTC RFC 3339).
  - **uptime_seconds** (integer) - Uptime in seconds.
  - **lifecycle** (string) - Lifecycle state: starting, running, or draining.

#### Response Example
```json
{
  "schema_version": 1,
  "live": true,
  "ready": true,
  "snapshot_at": "2026-09-10T20:55:46Z",
  "runtime": {
    "instance_id": "0123456789abcdef0123456789abcdef",
    "version": "0.0.0-dev",
    "flavor": "full",
    "started_at": "2026-09-10T20:55:40Z",
    "uptime_seconds": 6,
    "lifecycle": "running"
  }
}
```
```

--------------------------------

### Build CLI binary with Make targets

Source: https://github.com/openai/tunnel-client/blob/master/README.md

Builds the admin UI and the tunnel-client binary from a source checkout. The Make target stamps the checkout Git SHA into the version sent in User-Agent and X-Tunnel-Client-Version.

```bash
make admin-ui
make tunnel-client
./bin/tunnel-client help quickstart
```

--------------------------------

### Build tunnel-client from source

Source: https://github.com/openai/tunnel-client/blob/master/docs/onboarding.md

Build the client binary from the module root. `make admin-ui` refreshes embedded UI assets; you can skip it for a docs-only checkout when committed assets are already present.

```bash
make admin-ui
go build -o bin/tunnel-client ./cmd/client
```

--------------------------------

### GET /healthz

Source: https://github.com/openai/tunnel-client/blob/master/docs/enterprise-customer-onboarding.md

Health check endpoint for the tunnel client. Returns a success response if the client is running.

```APIDOC
## [GET] /healthz

### Description
Health check endpoint for the tunnel client. Returns a success response if the client is running.

### Method
GET

### Endpoint
http://127.0.0.1:8080/healthz

### Response
#### Success Response (200)
- No content or simple success indicator

#### Response Example
(No explicit response body documented)
```

--------------------------------

### GET /health/{component}

Source: https://github.com/openai/tunnel-client/blob/master/docs/health.md

Returns details for one registered component.

```APIDOC
## [GET] /health/{component}

### Description
Returns details for one registered component.

### Method
GET

### Endpoint
/health/{component}

### Parameters
#### Path Parameters
- **component** (string) - Required - The name of the component.

### Response
#### Success Response (200)
- **body** (object) - Component details. If the component is registered but disabled, returns `status: "disabled"`.

#### Error Response (404)
- **body** (string) - Component not found or unavailable.

#### Response Example
{
  "status": "ok"
}
```
Tokens:
Raw