openai/tunnel-client

Customer-run client for Secure MCP Tunnel: connect private or localhost MCP servers to ChatGPT, Codex, the Responses API, and AgentKit without exposing them to the public internet.

什么是 tunnel‑client？

tunnel-client 是一个命令行守护进程，允许你在安全的 OpenAI 托管隧道后运行私有的 MCP (Model Context Protocol) 服务器（即 OpenAI 的 ChatGPT、Codex 和其他产品所使用的 API）。该隧道使私有服务器能够被 OpenAI 服务访问，而无需将其暴露在公共互联网上。

为什么使用它

你在本地、虚拟机、Kubernetes 集群或任何私有网络中运行着 MCP 服务器。
贵组织的安全性策略禁止打开入站防火墙端口。
你需要一个生产级的守护进程来报告健康状态 (/healthz)、就绪状态 (/readyz)、指标和 UI，以便其他组件（例如 ChatGPT 连接器）可以安全地依赖它。

核心功能

功能	描述
安全隧道	通过 OpenAI 托管的隧道端点将私有 MCP 服务器连接到 OpenAI 的控制平面端点（ChatGPT、Codex、Responses API、AgentKit）。
内置演示模式	在客户端内运行一个微小的、无状态的 MCP 存根，用于快速测试 (`--embedded-stateless-mcp-stub`)。
Go SDK 集成	客户端可以使用内存传输与 Go MCP 服务器在进程内实例化，让你直接将隧道逻辑嵌入到你的 Go 应用程序中。
可观测性	公开 `/healthz`、`/readyz`、`/metrics` 和用于监控的 Web UI。
部署灵活性	可通过 Homebrew、Docker、Kubernetes 安装，或作为普通二进制文件运行。
权限模型	支持基于角色的隧道权限（读取、使用、管理），并可与 OpenAI 运行时/管理 API 密钥配合使用。
协议与 OpenAPI	提供完整的线路协议文档 (`docs/protocol.md`) 和 OpenAPI 合约 (`docs/openapi.json`)，用于以其他语言构建兼容的客户端。

典型工作流程

创建隧道：在 OpenAI Platform 中（或通过 tunnel-client admin tunnels create）。
导出隧道 ID 和运行时 API 密钥作为 CONTROL_PLANE_TUNNEL_ID 和 CONTROL_PLANE_API_KEY。

运行客户端，指向你的本地 MCP 服务器（或使用内置存根）。示例：

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

客户端与 OpenAI 建立安全隧道；ChatGPT 或 Codex 现在可以调用你的私有 MCP 端点，就像它们由 OpenAI 托管一样。

它在 AI 技术栈中的位置

Model Context Protocol (MCP) 是 OpenAI 的 LLM 支持服务所使用的底层请求/响应格式。
tunnel-client 是一个桥梁，让你自己的 MCP 实现（可能是自定义工具、数据存储或策略引擎）在保持在安全边界内的同时，参与到 OpenAI 托管的产品中。
它是一个企业级组件：签名的发布版本、SBOM、来源证明和严格的权限处理使其适用于受监管的环境。

快速入门清单

安装 – brew install openai/tools/tunnel-client（或使用 Docker/K8s）。
创建隧道和密钥 – 通过 OpenAI Platform UI 或 tunnel-client admin …。
运行 – tunnel-client help quickstart 然后 tunnel-client run …。
验证 – 检查健康端点，然后确认连接器出现在 ChatGPT 设置中。

了解更多

公共指南 – https://developers.openai.com/api/docs/guides/secure-mcp-tunnels
入门文档 – docs/onboarding.md
架构与权限 – docs/architecture.md, docs/permissions.md
协议规范与 OpenAPI – docs/protocol.md, docs/openapi.json
示例 – examples/go-sdk-inmemory（嵌入到 Go 进程中）。

总结

tunnel-client 是官方的 OpenAI 工具，可将私有 MCP 服务器安全地暴露给 OpenAI 的 LLM 支持服务，提供可观测性、基于角色的访问控制和多种部署选项，且无需打开入站网络端口。