tunnel-client: Securely Connect Private MCP Servers to OpenAI Services

Introduction

The tunnel-client is an open-source client developed by OpenAI, designed to securely connect private or localhost Model Context Protocol (MCP) servers to various OpenAI services. This includes ChatGPT, Codex, the Responses API, and AgentKit. It acts as a customer-run agent for the Secure MCP Tunnel, ensuring that your internal MCP servers can interact with OpenAI's platforms without being exposed to the public internet.

Why Use tunnel-client & Key Benefits

The tunnel-client addresses critical needs for developers and organizations working with OpenAI services, particularly concerning security and network architecture. Here are its key benefits:

• Secure Connectivity: It allows private or localhost MCP servers, whether on a laptop, VM, Kubernetes cluster, or private network, to reach OpenAI-hosted products without requiring new inbound firewall rules or public endpoints.
• Operational Visibility: The client provides an operator-visible daemon with /healthz, /readyz, /metrics, and /ui endpoints, offering insights into its status before any connector or API call depends on it. The admin UI also allows live log level switching and provides redacted support bundles for diagnostics.
• Flexible Deployment: It supports various deployment scenarios, including Docker, Kubernetes, and VMs, and can even be embedded as a Go SDK within your existing Go processes.
• Integration with OpenAI Ecosystem: Specifically designed to work seamlessly with ChatGPT connectors, Codex plugins, and other OpenAI APIs, facilitating agentic workflows.
• Robust Debugging: Features like tunnel-client doctor validate configurations, and the admin UI offers live log level switching, redacted support bundles, and Prometheus snapshots for debugging.

Installation

Using Homebrew (macOS/Linux)

Install tunnel-client from the official OpenAI tap:

brew install openai/tools/tunnel-client

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

tunnel-client --version
tunnel-client help quickstart

As a Go SDK

To embed tunnel-client directly into a Go process, you can use it as an SDK:

go get github.com/openai/tunnel-client

Building from Source

From a source checkout, you can build the client using standard Go tooling or Make targets:

go build ./...
go test ./...

For the full client, use make tunnel-client. For narrow runtime artifacts, use make runtime or make runtime-cloudflared.

Examples

Go SDK Integration

The module can run in the same process as a Go MCP server. Here's an example:

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)

Quickstart with CLI

For a guided setup and initial configuration, use the CLI's quickstart commands:

tunnel-client help quickstart
tunnel-client profiles samples list
tunnel-client profiles samples show sample_mcp_stdio_local
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

Codex Assistant

Interact with the Codex assistant directly from your terminal:

tunnel-client codex assistant "Summarize what tunnel-client is doing in this checkout."

Links

• GitHub Repository: openai/tunnel-client
• Public Secure MCP Tunnel Guide: developers.openai.com/api/docs/guides/secure-mcp-tunnels
• Onboarding Guide: docs/onboarding.md
• Architecture Diagrams: docs/architecture.md
• Deployment Guides: docs/deployment/overview.md
• Troubleshooting: docs/troubleshooting.md