openai/tunnel-client

What is tunnel‑client?

tunnel-client is a command‑line daemon that lets you run a private MCP (Model Context Protocol) server—the API that OpenAI’s ChatGPT, Codex and other products use—behind a secure, OpenAI‑hosted tunnel. The tunnel makes the private server reachable by OpenAI services without exposing it to the public internet.

Why you’d use it

• You have an MCP server running locally, on a VM, in a Kubernetes cluster, or any private network.
• Your organization’s security policy forbids opening inbound firewall ports.
• You need a production‑grade daemon that reports health (/healthz), readiness (/readyz), metrics and a UI, so other components (e.g., ChatGPT connectors) can depend on it safely.

Core capabilities

Feature	What it does
Secure tunnel	Connects a private MCP server to OpenAI’s control‑plane endpoints (ChatGPT, Codex, Responses API, AgentKit) via an OpenAI‑hosted tunnel endpoint.
Embedded demo mode	Runs a tiny, stateless MCP stub inside the client for quick testing (--embedded-stateless-mcp-stub).
Go SDK integration	The client can be instantiated in‑process with a Go MCP server using an in‑memory transport, letting you embed the tunnel logic directly in your Go application.
Observability	Exposes /healthz, /readyz, /metrics, and a web UI for monitoring.
Deployment flexibility	Install via Homebrew, Docker, Kubernetes, or run as a plain binary.
Permission model	Supports role‑based tunnel permissions (read, use, manage) and works with OpenAI runtime/admin API keys.
Protocol & OpenAPI	Full wire‑protocol documentation (docs/protocol.md) and an OpenAPI contract (docs/openapi.json) for building compatible clients in other languages.

Typical workflow

1. Create a tunnel in the OpenAI Platform (or via tunnel-client admin tunnels create).
2. Export the tunnel ID and a runtime API key as CONTROL_PLANE_TUNNEL_ID and CONTROL_PLANE_API_KEY.
3. Run the client, pointing it at your local MCP server (or use the embedded stub). Example:

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

4. The client establishes a secure tunnel to OpenAI; ChatGPT or Codex can now call your private MCP endpoints as if they were hosted by OpenAI.

How it fits into the AI stack

• Model Context Protocol (MCP) is the low‑level request/response format used by OpenAI’s LLM‑backed services.
• tunnel-client is the bridge that lets your own MCP implementation (perhaps a custom tool, data store, or policy engine) participate in OpenAI‑hosted products while staying inside your security perimeter.
• It is an enterprise‑grade component: signed releases, SBOMs, provenance attestation, and strict permission handling make it suitable for regulated environments.

---

Quick‑start checklist

1. Install – brew install openai/tools/tunnel-client (or use Docker/K8s).
2. Create tunnel & keys – via the OpenAI Platform UI or tunnel-client admin ….
3. Run – tunnel-client help quickstart then tunnel-client run ….
4. Verify – check health endpoint, then confirm the connector appears in ChatGPT settings.

---

Where to learn more

• Public guide – https://developers.openai.com/api/docs/guides/secure-mcp-tunnels
• On‑boarding docs – docs/onboarding.md
• Architecture & permissions – docs/architecture.md, docs/permissions.md
• Protocol spec & OpenAPI – docs/protocol.md, docs/openapi.json
• Examples – examples/go-sdk-inmemory (embedding in a Go process).

---

TL;DR

tunnel-client is the official OpenAI tool that securely exposes a private MCP server to OpenAI’s LLM‑backed services, providing observability, role‑based access, and multiple deployment options—all without opening inbound network ports.