openai/tunnel-client

openai/tunnel-client

Language: Go

License: Apache-2.0

Stars: 91

Forks: 10

Open issues: 0

Created: 2025-12-10T00:39:35Z

Pushed: 2026-06-11T00:57:40Z

Default branch: master

Fork: no

Archived: no

README:

Secure MCP Tunnel client

tunnel-client is the customer-run agent behind Secure MCP Tunnel. It connects a private or localhost MCP (Model Context Protocol) server to ChatGPT, Codex, the Responses API, and AgentKit through an OpenAI-hosted MCP tunnel endpoint, while keeping the MCP server off the public internet.

Use it when:

• You have an MCP server on a laptop, VM, Kubernetes cluster, or private

network and need an OpenAI-hosted product to reach it.

• Security will not approve a new inbound firewall rule or public endpoint for

the MCP server.

• You want an operator-visible daemon with /healthz, /readyz, /metrics,

and /ui before a connector or API call depends on it.

If you searched for "secure MCP tunnel", "MCP tunnel ChatGPT", "connect local MCP server to ChatGPT", "connect local MCP server to Codex", "localhost to ChatGPT", or "Codex local MCP", start with tunnel-client help quickstart, then read the onboarding guide below.

Start Here

• **Need the shortest working path from localhost or a private MCP server to

ChatGPT or Codex?** Start with [docs/onboarding.md](docs/onboarding.md).

• Need the customer-shareable network and trust-boundary story? Read

[docs/architecture.md](docs/architecture.md).

• Need roles, groups, tunnel IDs, or API keys? Read

[docs/permissions.md](docs/permissions.md).

• Need Docker, Kubernetes, or VM deployment guidance? Read

[docs/deployment/overview.md](docs/deployment/overview.md).

• Need to debug readiness, connector discovery, or OAuth? Read

[docs/troubleshooting.md](docs/troubleshooting.md).

Documentation Map

• Public Secure MCP Tunnel guide:

`developers.openai.com/api/docs/guides/secure-mcp-tunnels`

• Shareable end-user guide: [docs/end-user-guide.md](docs/end-user-guide.md)
• Start here: [docs/onboarding.md](docs/onboarding.md)
• Permissions, roles, and groups: [docs/permissions.md](docs/permissions.md)
• Architecture diagrams: [docs/architecture.md](docs/architecture.md)
• Connector behavior: [docs/connectors.md](docs/connectors.md)
• Enterprise customer handoff:

[docs/enterprise-customer-onboarding.md](docs/enterprise-customer-onboarding.md)

• Configuration reference: [docs/configuration.md](docs/configuration.md)
• Deployment guides: [docs/deployment/overview.md](docs/deployment/overview.md)
• Troubleshooting: [docs/troubleshooting.md](docs/troubleshooting.md)
• Development & testing: [docs/development.md](docs/development.md)
• Roadmap / design notes: [docs/roadmap.md](docs/roadmap.md)

To generate the shareable guide output locally:

make end-user-guide-screenshots
make end-user-guide-html
make end-user-guide-slides

For Codex / Claude / Copilot

If you want the shortest supported path from a local or localhost MCP server to ChatGPT or Codex, start with tunnel-client help quickstart. For Codex plugin lifecycle work, use the native tunnel-client runtimes ... and tunnel-client admin-profiles ... command trees surfaced by tunnel-client help plugin.

Supervision choice:

• Use tunnel-client run ... when you intentionally want a foreground daemon

attached to the current terminal.

• For a long-lived local runtime managed by Codex, prefer

tunnel-client runtimes connect .... Do not use nohup or disown as the tunnel-client supervision path.

• After runtimes connect, check tunnel-client runtimes status

before reporting success. Only report success when status shows the managed runtime running with health reported. Use --json when Codex needs the explicit process_running, healthy, and ready fields.

Use these exact setup pages during first use:

• Tunnels management and supported tunnel-client download:

https://platform.openai.com/settings/organization/tunnels

• Organization roles: https://platform.openai.com/settings/organization/people/roles
• Organization groups: https://platform.openai.com/settings/organization/people/groups
• Runtime API keys: https://platform.openai.com/settings/organization/api-keys
• Admin API keys: https://platform.openai.com/settings/organization/admin-keys
• ChatGPT connector settings: https://chatgpt.com/#settings/Connectors

Which value comes from where:

• CONTROL_PLANE_TUNNEL_ID: create or inspect it in Tunnels management, or via

tunnel-client admin tunnels create|list|get ... with OPENAI_ADMIN_KEY.

• CONTROL_PLANE_API_KEY: create it in Runtime API keys; this is the key used

by tunnel-client doctor and tunnel-client run.

• OPENAI_ADMIN_KEY: only for `tunnel-client admin tunnels

list|create|update|delete`. Do not use the admin key for the long-lived daemon.

Required tunnel permissions:

• Runtime users and the principal that creates CONTROL_PLANE_API_KEY need

Tunnels Read + Use.

• Tunnel managers need Tunnels Read + Manage, plus Use if they also

run the daemon or attach ChatGPT connectors.

• Admin-key creators need the Platform admin-key permission in addition to any

tunnel permissions they need.

See [docs/permissions.md](docs/permissions.md) for the group/role workflow and screenshots.

Binary-first flow:

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

If you need the tunnel id or runtime/admin keys first, open the matching URL above before running init. If your rollout has self-serve tunnel access, create the tunnel yourself in Tunnels management or with tunnel-client admin tunnels create, then export the returned id as CONTROL_PLANE_TUNNEL_ID and a separate runtime key as CONTROL_PLANE_API_KEY. Create or verify the connector from the ChatGPT settings URL above only while tunnel-client run ... is healthy, and keep the daemon running for connector discovery and every MCP call from ChatGPT.

The Platform…