项目介绍
Secure MCP Tunnel client 是 OpenAI 官方维护的客户侧守护进程。它部署在笔记本、虚拟机、Kubernetes 集群或私有网络中，通过出站 HTTPS 长轮询接收 OpenAI Secure MCP Tunnel 的请求，再把请求交给本地 stdio 或 Streamable HTTP MCP 服务。这样不必把 MCP 监听端口暴露到公网，但请求、工具参数、响应和部分 OAuth 流量仍会经过 OpenAI 产品运行时与 tunnel-service。项目的操作面较完整，包含 profile、doctor、健康检查、指标、本地管理界面、代理与私有 CA 配置，并提供 Codex 插件管理长驻 runtime。适合确有私有 MCP 接入需求且能审查身份、数据流和部署边界的团队。
核心功能
私有 MCP 出站桥接
客户侧客户端通过出站 HTTPS 轮询 OpenAI tunnel-service，把指定 tunnel 的 MCP JSON-RPC 请求转发到本地或私有网络中的 main binding。
stdio 与 Streamable HTTP
main channel 可绑定本地子进程命令或可达的 HTTP(S) MCP URL；HTTP 还支持 Unix socket、代理、自定义 CA 和 mTLS。
Profile 与启动前诊断
init 可生成经过校验的命名 profile，doctor --explain 会在守护进程启动前检查配置、控制面和 MCP 探测结果。
Codex runtime 管理
仓库内置 tunnel-mcp 插件，由原生 runtimes 命令负责创建、连接、列举、检查、停止和清理本地 runtime。
可观测性与本地管理界面
守护进程提供存活、就绪、指标和本地 UI，可显示 channel、控制面、代理、日志与运行状态。
OAuth 与多副本支持
连接器路径支持受保护资源元数据发现、Harpoon 路由和 OAuth 相关流量；v0.0.14 增加 MCP 2026-07-28 OAuth 与 Harpoon 多副本能力。
安装与连接
macOS 推荐用 Homebrew 安装，先核对 Tunnels 权限并准备 tunnel ID、独立运行时 API Key 与本地 MCP，再用 init 生成 profile、doctor --explain 诊断，最后以前台 run 或 Codex 管理的 runtime 启动。
让 AI Agent 帮你安装
把这段话发送给 Codex、Claude Code 或其他可以操作本地环境的 AI Agent。
请从 https://github.com/openai/tunnel-client 安装 Secure MCP Tunnel client。先阅读 README、docs/onboarding.md、docs/permissions.md、docs/architecture.md 与 docs/configuration.md。macOS 使用 brew install openai/tools/tunnel-client，不要下载未公证 ZIP 或绕过 Gatekeeper。先确认我已有 OpenAI Tunnels 权限、目标 tunnel ID，以及只具备 Tunnels Read 和 Use 的独立运行时 API Key；不要要求我在聊天中粘贴密钥，也不要把密钥写进命令行、profile 或日志，使用 env: 或 file: 引用。确认本地 MCP 是 stdio 命令还是 Streamable HTTP URL 后，用 init 创建命名 profile，运行 doctor --explain，再启动 runtime。只有 /healthz、/readyz 和控制面轮询都正常后，才执行一次无副作用验证。任何创建 tunnel、使用 admin key、开放远程 UI、修改防火墙、写入系统服务或发送真实业务数据的操作都先征得我的明确同意。- macOS 与 Homebrew；其他平台按 release 或源码构建说明选择受支持路径
- 组织或工作区已获得 OpenAI Tunnels 功能，并已创建或分配 tunnel ID
- 具备 Tunnels Read 与 Use 的独立运行时 API Key；不要把 admin key 用于常驻 runtime
- 可从 tunnel-client 主机访问的 stdio 命令或 Streamable HTTP MCP URL
- 如果在 ChatGPT 使用，连接器管理员还需让 tunnel 对目标 workspace 可见
brew install openai/tools/tunnel-client- 1安装并确认版本
运行 brew install openai/tools/tunnel-client，然后执行 tunnel-client --version 与 tunnel-client help quickstart。2026-09-09 核对的最新稳定版本是 v0.0.14。
- 2准备最小权限的 tunnel 身份
在 OpenAI Platform 中确认已有 tunnel ID，并为常驻客户端准备只有 Tunnels Read 与 Use 的运行时 API Key。创建或修改 tunnel 才使用另行保管的 admin key。
- 3生成命名 profile
对本地 stdio MCP 可运行 tunnel-client init --sample sample_mcp_stdio_local --profile local-stdio --tunnel-id tunnel_... --mcp-command "python /path/to/server.py"。将真实 runtime key 放入环境变量或文件引用，不要写进 profile。
- 4在启动前诊断
运行 tunnel-client doctor --profile local-stdio --explain，逐项处理 tunnel 权限、控制面连通性、MCP 启动或 OAuth 探测错误。不要把仅有 healthz 视为连接器可用。
- 5启动并检查就绪状态
前台测试可运行 tunnel-client run --profile local-stdio。根据输出的本地地址检查 /healthz、/readyz 和 /metrics；Codex 长驻运行优先用 runtimes connect，并随后运行 runtimes status <alias>。
- 6在产品端执行最小验证
在 ChatGPT 连接器中选择对应 Tunnel，或从 Codex、Responses API、AgentKit 发起一次 tools/list 或只读工具调用。确认目标 MCP、返回范围、OAuth 行为与日志脱敏符合预期。
依次运行 tunnel-client --version、tunnel-client doctor --profile local-stdio --explain 和 tunnel-client run --profile local-stdio。另开终端读取 /healthz 与 /readyz，只有存活和就绪均成功、控制面轮询正常，再从目标 OpenAI 产品执行一次无副作用的 tools/list 或只读工具调用。
- Homebrew 是 macOS 官方支持路径；直接下载 ZIP 当前未公证，不要用 xattr、spctl 或 Open Anyway 绕过 Gatekeeper。
- CONTROL_PLANE_API_KEY 是长期 runtime 凭据；OPENAI_ADMIN_KEY 只用于 tunnel CRUD，二者应分离。
- profile 中的 secret 字段优先使用 env:VARNAME 或 file:/path，不要提交明文密钥。
- 默认健康监听应保持在 127.0.0.1；远程暴露 UI、日志或指标前必须增加独立保护。
- 停止本地 runtime 不会删除远端 tunnel；删除需要单独的管理权限与操作。
使用场景
让 ChatGPT 使用内网工具
把仅能从企业网络访问的 MCP 服务保留在私网，通过 Workspace 可见的 tunnel 提供给受控 ChatGPT 连接器。
Codex 连接本地 stdio MCP
由 tunnel-mcp 插件与 runtimes 命令管理本地子进程、profile、健康地址和长驻 runtime。
桥接私有 HTTP MCP
从 VM、Kubernetes 或专用主机访问私有 Streamable HTTP 服务，同时使用代理、私有 CA、Unix socket 或 MCP 侧 mTLS。
受控 OAuth 连接器
在理解 Harpoon、protected-resource metadata 和浏览器授权边界后，让 OpenAI 产品对接受 OAuth 保护的私有 MCP。
使用评价
从公开仓库与 v0.0.14 发布材料看，Secure MCP Tunnel client 的优势是把私有 MCP 接入、权限拆分、profile 诊断、运行管理和可观测性放进同一个官方客户端，并为 release 附带较完整的供应链证据。最需要防止的误解是把“不开放公网监听端口”理解成“数据完全留在本地”。MCP 载荷仍经过 OpenAI 产品运行时和 tunnel-service，runtime key 也会作为控制面认证发送给 OpenAI。它适合经过数据治理与权限审查的组织级接入，不适合作为完全本地、零第三方数据路径的替代方案。
值得一试的地方
- OpenAI 官方实现，与 ChatGPT、Codex、Responses API 和 AgentKit 的隧道路径有直接文档对应
- 不要求为 MCP 服务开放入站公网端口
- 同时支持 stdio 与 Streamable HTTP，并覆盖代理、私有 CA、Unix socket 和 mTLS
- doctor、readyz、metrics、本地 UI 与 Codex runtime 管理降低部署诊断成本
- 发布包含校验和、来源证明、SBOM、漏洞与许可证证据
使用前要知道
- 需要 OpenAI Tunnels 产品权限，不能作为任意 MCP 客户端的通用隧道替代品
- MCP 载荷与部分 OAuth 流量会经过 OpenAI，无法满足严格全本地数据边界
- macOS release ZIP 未公证，官方支持安装路径限于 Homebrew
- 仓库未提供独立 SECURITY.md，安全材料需要从多份架构和发布文档中综合判断
- 本文没有完成真实凭据、MCP 服务和产品端的端到端验证
README
Secure MCP Tunnel client
Overview
OpenAI 官方的自托管隧道客户端，让 ChatGPT、Codex、Responses API 与 AgentKit 通过 OpenAI Secure MCP Tunnel 访问客户网络内的本地或私有 MCP 服务，无需把 MCP 监听端口暴露到公网。 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.
Getting started
- macOS 推荐用 Homebrew 安装，先核对 Tunnels 权限并准备 tunnel ID、独立运行时 API Key 与本地 MCP，再用 init 生成 profile、doctor --explain 诊断，最后以前台 run 或 Codex 管理的 runtime 启动。
- 客户端在客户控制的网络内运行，通过 OpenAI API 的 tunnel poll 和 response 路径接收请求与回传结果，不需要开放入站 tunnel 端口。
- 每个配置必须包含控制面 API Key、tunnel ID，以及 main channel 的 MCP_SERVER_URL 或 MCP_COMMAND。配置优先级是命令行、环境变量、YAML、默认值。
- 依次运行 tunnel-client --version、tunnel-client doctor --profile local-stdio --explain 和 tunnel-client run --profile local-stdio。另开终端读取 /healthz 与 /readyz，只有存活和就绪均成功、控制面轮询正常，再从目标 OpenAI 产品执行一次无副作用的 tools/list 或只读工具调用。
Configuration
brew install openai/tools/tunnel-client