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.

This CLI and its Go SDK run beside your private MCP server. Applications call the OpenAI-hosted /v1/mcp/{tunnel_id} endpoint through their MCP transport; the runtime receives those requests and delivers responses. The poll/response endpoints are the runtime's queue protocol for client implementers. See the architecture for the request flow and the protocol when building a compatible runtime.

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.
• Need the customer-shareable network and trust-boundary story? Read docs/architecture.md.
• Need roles, groups, tunnel IDs, or API keys? Read docs/permissions.md.
• Need Docker, Kubernetes, or VM deployment guidance? Read docs/deployment/overview.md.
• Need to debug readiness, connector discovery, or OAuth? Read docs/troubleshooting.md.
• Building a compatible client in another language? Read docs/protocol.md and use docs/openapi.json. Optional client features use the common X-Tunnel-Client-Capabilities header.
• Upgrading for server-directed polling placement? Read the routing correction and activation notes. Supporting clients work with existing services immediately; corrections are enabled separately after client release. No configuration change is needed.
• Using MCP timing or distributed tracing? Read the timing release and rollback guidance. Trace forwarding is disabled by default; opt in with --mcp.forward-trace-context to carry W3C trace context in MCP params._meta over stdio and Streamable HTTP. Opt-in local span export uses --tracing.enabled --tracing.file=/private/new-trace.jsonl. Complete traces require compatible service queue handoff and caller parent propagation first.
• Forwarding the original HTTP request ID? MCP HTTP forwarding is enabled by default. Use --forward-request-id=mcp,harpoon to include Harpoon REST requests, --forward-request-id=mcp,oauth to include eligible queued OAuth discovery requests, or --forward-request-id=none to disable automatic forwarding. The same setting is available as FORWARD_REQUEST_ID or top-level YAML forward_request_id; see request ID forwarding.
• Using a namespaced tunnel ID? Preserve the full ID returned by the service. The client accepts legacy IDs and aliases with a four-character namespace; see tunnel identifiers.
• Embedding an MCP server directly in a Go process? Use the Go SDK with the MCP SDK's in-memory transport; see examples/go-sdk-inmemory.

Try the embedded demo

With a runtime API key and tunnel ID, run the built-in server_info, echo, and uppercase tools without a separate MCP server:

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

--embedded-stateless-mcp-stub uses stateless MCP handling even when a client sends initialize and notifications/initialized. It issues no MCP session ID, and these demo tools do not require MCP session affinity between processes. OAuth and application state have separate requirements.

--embedded-mcp-stub keeps its existing compatibility behavior: legacy initialization and session requests use stateful handling; self-contained modern discovery and tool requests use stateless handling. Choose one embedded mode per run. Both share the embedded listen-address, Unix-socket, server-name, and server-version options; see embedded demo configuration for defaults and target conflicts.

Embed as a Go SDK

The module can run in the same process as a Go MCP server. The MCP server does not need to bind a port or use stdio: give the server side of an in-memory MCP transport pair to your server and the client side to tunnelclient.New.

go get github.com/openai/tunnel-client

import (
    "context"

    "github.com/modelcontextprotocol/go-sdk/mcp"
    tunnelclient "github.com/openai/tunnel-client"
)

ctx := context.Background()
server := mcp.NewServer(&mcp.Implementation{Name: "my-server", Version: "1.0.0"}, nil)
serverTransport, tunnelTransport := mcp.NewInMemoryTransports()
go server.Run(ctx, serverTransport)

client, err := tunnelclient.New(tunnelclient.Config{
    TunnelID: "tunnel_0123456789abcdef0123456789abcdef",
    APIKey:   apiKey,
}, tunnelTransport)
if err != nil {
    return err
}
return client.Run(ctx)

The runnable Go SDK example registers an echo tool and connects it to the OpenAI Tunnel control plane.

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
• Start here: docs/onboarding.md
• Permissions, roles, and groups: docs/permissions.md
• Architecture diagrams: docs/architecture.md
• Connector behavior: docs/connectors.md
• Wire protocol for client implementers: docs/protocol.md
• OpenAPI contract: docs/openapi.json
• Enterprise customer handoff: docs/enterprise-customer-onboarding.md
• Configuration reference: docs/configuration.md
• Deployment guides: docs/deployment/overview.md
• Bundled Cloudflare companion: docs/deployment/cloudflared.md
• Troubleshooting: docs/troubleshooting.md, including DNS diagnostic logs for Android / Termux.
• Development & testing: docs/development.md
• In-memory Go SDK example: examples/go-sdk-inmemory
• Roadmap / design notes: docs/roadmap.md

Install with Homebrew

On macOS, Homebrew is the supported installation path. Directly downloaded release ZIPs are not currently notarized and can be blocked by Gatekeeper. If a manually downloaded archive is blocked, do not use xattr, spctl, or Open Anyway to bypass the check; install from the official OpenAI tap instead:

brew install openai/tools/tunnel-client

Verify the installed version, then start with the guided setup:

tunnel-client --version
tunnel-client help quickstart

The Formula installs the matching tunnel-client, bundled cloudflared, and companion manifest together, while exposing only the tunnel-client command. It also installs Bash, Zsh, and Fish completions for that version. If your shell does not load them automatically, follow Homebrew's shell completion setup. For Docker, Kubernetes, or VM deployments, see docs/deployment/overview.md.

To generate the shareable guide output locally:

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

Start at macOS login

The Homebrew Formula supports brew services. It supervises tunnel-client run using the profile at $(brew --prefix)/etc/tunnel-client.yaml, starts at login, and restarts the runtime after it exits. Installation and upgrades do not create or replace that profile.

First, select the profile you already configured. If it belongs to a managed alias, find its profile_path with tunnel-client runtimes status <alias> --json, then run tunnel-client runtimes stop <alias> before starting the service. Copy the profile to the service location, preserving your custom settings:

service_profile="$(brew --prefix)/etc/tunnel-client.yaml"
if [ -e "$service_profile" ]; then
  cp -p "$service_profile" "$service_profile.backup.$(date +%Y%m%d%H%M%S)"
fi
install -m 600 /absolute/path/to/existing-profile.yaml "$service_profile"

Use absolute paths in this profile, including paths to MCP executables, working directories, and secret files. The service includes Homebrew's bin and sbin on PATH, but does not load your interactive shell configuration. Replace shell-only env: references with persistent references