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

This repository profile is provided by osrepos.com, an open source repository discovery platform.

Source: osrepos.com
Repository profile: https://osrepos.com/repo/openai-tunnel-client
Generated for open source discovery and AI-assisted research.

The `tunnel-client` is an OpenAI-developed client that enables secure connections between private or localhost Model Context Protocol (MCP) servers and OpenAI services like ChatGPT, Codex, and AgentKit. It allows developers to integrate their internal MCP servers without exposing them to the public internet, ensuring enhanced security and operational control. This tool is ideal for scenarios requiring secure access from private networks to OpenAI's powerful AI models.

GitHub: https://github.com/openai/tunnel-client
OSRepos URL: https://osrepos.com/repo/openai-tunnel-client

## Summary

The `tunnel-client` is an OpenAI-developed client that enables secure connections between private or localhost Model Context Protocol (MCP) servers and OpenAI services like ChatGPT, Codex, and AgentKit. It allows developers to integrate their internal MCP servers without exposing them to the public internet, ensuring enhanced security and operational control. This tool is ideal for scenarios requiring secure access from private networks to OpenAI's powerful AI models.

## Topics

- Go
- OpenAI
- ChatGPT
- Codex
- Agentic AI
- Secure Tunnel
- CLI
- Developer Tools

## Repository Information

Last analyzed by OSRepos: Wed Sep 02 2026 12:14:44 GMT+0100 (Western European Summer Time)
Detail views: 2
GitHub clicks: 0

## Safety Notice

OSRepos shares public repositories for knowledge and discovery only. Review source code, dependencies, licenses, and security implications before running or installing anything.

## Content

## 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:

bash
brew install openai/tools/tunnel-client


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

bash
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:

bash
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:

bash
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:

go
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:

bash
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:

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


## Links

*   **GitHub Repository:** [openai/tunnel-client](https://github.com/openai/tunnel-client){:target="_blank"}
*   **Public Secure MCP Tunnel Guide:** [developers.openai.com/api/docs/guides/secure-mcp-tunnels](https://developers.openai.com/api/docs/guides/secure-mcp-tunnels){:target="_blank"}
*   **Onboarding Guide:** [docs/onboarding.md](https://github.com/openai/tunnel-client/blob/master/docs/onboarding.md){:target="_blank"}
*   **Architecture Diagrams:** [docs/architecture.md](https://github.com/openai/tunnel-client/blob/master/docs/architecture.md){:target="_blank"}
*   **Deployment Guides:** [docs/deployment/overview.md](https://github.com/openai/tunnel-client/blob/master/docs/deployment/overview.md){:target="_blank"}
*   **Troubleshooting:** [docs/troubleshooting.md](https://github.com/openai/tunnel-client/blob/master/docs/troubleshooting.md){:target="_blank"}