Secure MCP Tunnel 客户端
让 OpenAI 产品安全访问本地或私有 MCP 服务，无需开放公网入口。
证据清楚区分运行时密钥与管理员密钥、列出最小角色权限，并说明 HTTPS 长轮询、MCP 转发、OAuth 元数据读取、客户端实例标识和管理界面的数据流。敏感令牌可通过环境变量或独立秘密文件传递，支持 mTLS，支持包会脱敏日志、指标和配置。发布流程固定 GitHub Actions 提交，生成 SHA-256、容器 SBOM 和来源证明；但归档校验和的签名步骤仍是可选且被注释，因此依赖安全扣分。管理 CRUD、配置写入、运行时启动/停止及插件安装/卸载均被明确披露，但所给材料没有证明每项有交互式确认，故 user_confirmation 和 external_effects 未满分。提供 stop、rm、uninstall 和前台运行等撤销路径，但未完整说明误删隧道或覆盖配置后的恢复，因此 rollback 扣分。官方仓库路径、模块路径、镜像来源标签、许可证及经验证的 OpenAI 发布者出处使来源归属充分。
README、模块清单和发布工作流在模块名、Go 版本、平台矩阵、语义版本与捆绑 cloudflared 方面相互一致。CI 包含模块下载、完整 Go 测试、发布版本校验、伴随程序版本校验、公开 URL 验证和 Homebrew 冒烟安装。doctor --explain、健康/就绪端点、结构化运行时状态及工作流中的具体错误输出提供了充分的失败信息。依赖均有版本约束且发布覆盖主要桌面/服务器架构，但运行仍依赖 OpenAI 控制平面、网络、外部 MCP 服务，并且仅凭所给静态文件无法确认所有依赖制品持续可得，因此 dependency_availability 扣分。
材料明确覆盖笔记本、VM、Kubernetes、私有网络、前台守护进程、受管本地运行时、容器、Homebrew、源码构建和进程内 Go SDK，并按 ChatGPT、Codex、Responses API、AgentKit及兼容客户端开发者区分场景。它明确限定主通道、附加通道、Harpoon 注册条件、支持的 MCP 传输、OAuth 元数据来源和可选后端。命令树、精确启动条件、成功判定字段以及前台与长期运行方式使触发边界清晰。跨平台发布矩阵、代理/私有 CA 样例、mTLS、stdio/HTTP/内存传输和启动等待配置充分支持环境适配，未发现需要扣分的具体缺口。
README 提供按任务组织的入口、完整文档地图、安装与构建命令、配置来源、示例、故障排查入口和 SDK 样例。命令及环境变量命名稳定且具体，旧版单数 API 路径的迁移兼容策略也被明确说明。Apache-2.0 元数据与完整 LICENSE 一致。语义版本标签、源码版本嵌入、稳定/预发布别名规则和自动生成发布说明均存在，但没有提供独立的变更日志内容，因此 versioning_changelog 扣分。材料提及限制和条件，例如平台覆盖、Redis/Rust 的可选构建要求、守护进程持续运行要求及旧路径迁移，但被引用的 roadmap、troubleshooting 等文件内容未提供，无法确认完整限制清单，故 known_limitations 未满分。官方组织出处、发布工作流以及 cloudflared 安全补丁责任说明使维护责任和更新路径清楚。
产出直接可供运维使用：有引导式初始化、配置诊断、健康/就绪/指标端点、管理 UI、结构化 JSON 状态、脱敏支持包、多种部署包和可运行 SDK 示例。其核心增量价值清晰，即无需开放入站防火墙或公开 MCP 服务即可连接 OpenAI 托管产品，并增加可观测性和本地监督。成本与收益的基本取舍有所披露，包括长期守护进程、控制平面依赖、伴随 cloudflared、权限与密钥配置以及部署选择；但没有资源消耗、延迟、容量或运维成本数据，所以 cost_benefit 未满分。
主要声明关联到具体命令、环境变量、HTTP 路径、请求头、状态字段、平台矩阵和工作流步骤，具有较强可追踪性。README 中的许可证、模块路径、版本策略和发布平台可由 LICENSE、go.mod 及两个发布工作流交叉印证；固定 action 提交、版本检查、校验和、SBOM 和来源证明进一步增强审计性。不过大量运行时安全与行为声明仅出现在 README，所给证据没有核心实现文件或相应测试来逐项印证，且部分产品性陈述未明确标为设计意图或已验证事实，因此 fact_inference_separation 扣分。
- 这是低置信度的静态审查；未执行二进制、测试、网络连接、安装流程或发布制品验证。
- 所给材料缺少核心隧道、凭据处理、脱敏、管理 CRUD 和运行时监督实现，README 中的相关声明不能视为独立验证。
- 发布归档提供 SHA-256 校验和，但工作流中的 GPG 签名步骤被注释为可选；生产使用者应固定精确版本或摘要，并通过可信渠道核验制品。
- 该客户端会把私有 MCP 请求和响应经 OpenAI 控制平面中继，并可能读取 OAuth 元数据；部署前应核对数据分类、日志脱敏范围、组织权限和 MCP 工具自身的副作用。
- 管理员命令包括隧道删除，运行时命令包括 rm，配置初始化会写入文件；现有材料没有完整展示逐项确认或误操作恢复机制。
这个 Agent 能做什么，适合哪些场景？
Secure MCP Tunnel 客户端是运行在客户环境中的 Go 客户端，用于把笔记本、虚拟机、Kubernetes 集群或私有网络内的 MCP 服务连接到 OpenAI 托管的隧道端点。它通过 HTTPS 长轮询 OpenAI 控制平面，接收 JSON-RPC 请求，再经 Streamable HTTP、stdio 或进程内传输将请求转发给目标 MCP 服务。项目同时提供命令行程序、可嵌入 Go 进程的 SDK、原生运行时管理命令，以及面向 Codex 的助手和插件入口。运维界面包括 `/healthz`、`/readyz`、`/metrics` 和 `/ui`，并支持运行时日志级别调整和经过脱敏的支持包导出。它适合不能新增入站防火墙规则、但能主动连接 OpenAI 控制平面的组织；核心链路依赖 OpenAI Secure MCP Tunnel，并非通用的多供应商隧道。
启动时，客户端使用 GET /v1/tunnels/{tunnel_id} 获取隧道元数据，并从 MCP 服务读取 OAuth Protected Resource Metadata 以生成诊断信息。随后它通过 GET /v1/tunnels/{tunnel_id}/poll 长轮询控制平面，接收请求后按 main、附加频道或已注册的 harpoon 目标进行路由，通过 Streamable HTTP、stdio 或 Go 内存传输调用 MCP 服务，再以 POST /v1/tunnels/{tunnel_id}/response 返回结果。它还可转发 Streamable HTTP 会话终止请求，为控制平面连接配置独立的客户端证书和私钥，并在默认 API 主机下自动使用 mTLS 端点。tunnel-client init 创建并校验配置，doctor --explain 检查启动条件，run 启动前台轮询进程，runtimes create|connect|list|status|stop|rm 管理由 Codex 使用的本地受管运行时。管理服务输出健康、就绪和 Prometheus 指标，Web UI 展示实例标识、频道状态与日志，还能生成包含近期日志、指标快照及脱敏运行时 YAML 的支持包。
- 企业平台团队需要让 ChatGPT 访问 Kubernetes 私有网络中的 MCP 服务，但安全策略禁止创建公网端点或新的入站防火墙规则。
- 开发者在笔记本上运行 localhost MCP 服务，希望通过最短的命令行流程将其用于 ChatGPT 或 Codex。
- 运维人员部署长期运行的隧道守护进程，并需要用
/healthz、/readyz、/metrics和/ui接入健康检查、监控与故障排查。 - Go 服务作者希望把 MCP 服务和隧道客户端嵌入同一进程，通过
mcp.NewInMemoryTransports()避免绑定端口或使用 stdio。 - 需要私有 PKI、出站代理、mTLS 或 Cloudflare 隧道伴随进程的团队，希望使用内置配置样例和部署路径。
- Codex 用户希望通过
runtimes connect管理长期本地连接，并在交付前明确检查进程是否运行、健康且就绪。
这个 Agent 有哪些优点和局限？
- 采用客户侧主动长轮询，无需为私有 MCP 服务开放公网端点或新增入站防火墙规则。
- 同时支持 Streamable HTTP、stdio 和 Go 进程内 MCP 传输，可覆盖独立服务、命令行服务和嵌入式部署。
- 内置
/healthz、/readyz、/metrics、管理 UI、动态日志级别及脱敏支持包，运维可观测性较完整。 - 提供 Homebrew、源码构建、Docker/Kubernetes/VM 文档以及多平台发布归档，并包含固定版本的
cloudflared伴随程序。 - 明确区分运行时 API 密钥与管理 API 密钥，并记录 Tunnels Read、Use、Manage 等权限要求。
- 核心通信依赖 OpenAI 托管的 Secure MCP Tunnel 控制平面，因此无法直接作为供应商无关的 MCP 隧道使用。
- 采用 ChatGPT 连接器或 OpenAI API 前，需要准备隧道 ID、运行时密钥和正确的组织权限；管理工作流还可能需要单独的管理密钥。
- 连接器发现及所有远程 MCP 调用都依赖客户端持续运行，进程不健康或未就绪会中断访问。
- 从源码构建需要 Go；重建管理 UI 还需执行单独的资源生成步骤。
- 生产部署若使用发布镜像或 Cloudflare 伴随程序，需要管理精确版本或镜像摘要、平台架构以及安全更新责任。
如何安装或部署这个 Agent？
Homebrew 安装：
brew install openai/tools/tunnel-client
tunnel-client --version
tunnel-client help quickstart从源码构建需要 Go 工具链：
go build ./...
go test ./...
make admin-ui
go build -o bin/tunnel-client ./cmd/client
./bin/tunnel-client help quickstart嵌入 Go 服务时安装模块：
go get github.com/openai/tunnel-client首次运行前，需要在 OpenAI 平台取得 CONTROL_PLANE_TUNNEL_ID，并创建具有 Tunnels Read + Use 权限的独立运行时 API 密钥 CONTROL_PLANE_API_KEY。只有执行 tunnel-client admin tunnels list|create|update|delete 时才使用 OPENAI_ADMIN_KEY；不要将管理密钥交给长期运行的守护进程。
如何使用这个 Agent？
创建本地 stdio MCP 配置并验证：
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-stdiorun 会将守护进程附着在当前终端；连接器发现和每次 MCP 调用期间都必须保持其运行。需要由 Codex 管理长期进程时，使用 tunnel-client runtimes connect ...，随后执行 tunnel-client runtimes status <alias>；自动化检查可加 --json 并读取 process_running、healthy 和 ready。只有在客户端健康运行时，才应从 ChatGPT 的连接器设置中创建或验证连接器。若采用托管 Cloudflare 配置，可运行：
tunnel-client run --cloudflared.managed --control-plane.tunnel-id tunnel_0123456789abcdef0123456789abcdef --mcp.server-url https://mcp.example.com/mcp这个 Agent 与同类方案有什么区别？
与直接为 MCP 服务创建公网入口相比，该客户端采用客户网络向 OpenAI 控制平面发起的出站 HTTPS 长轮询，避免新增入站防火墙规则。tunnel-client run 适合附着当前终端的前台运行；tunnel-client runtimes connect 更适合由 Codex 管理的长期本地运行时。原始二进制提供最小安装面，tunnel-client codex assistant 提供 Codex 原生终端入口，而内置插件则在 Codex 中暴露 runtimes 与 admin-profiles 工作流。对于 MCP 连接，Streamable HTTP 适合网络服务，stdio 适合本地子进程，Go SDK 的内存传输适合同进程嵌入。
常见问题
需要开放入站端口吗？
运行时密钥需要什么权限？
CONTROL_PLANE_API_KEY 的主体需要 Tunnels Read + Use。管理隧道需要 Read + Manage；如果同一主体还运行守护进程或连接 ChatGPT，则也需要 Use。如何确认连接已经可以使用？
tunnel-client doctor --profile <name> --explain。受管运行时还应执行 tunnel-client runtimes status <alias>；只有进程正在运行且健康状态已上报时才应报告成功，自动化场景可检查 JSON 中的 process_running、healthy 和 ready。能否不运行独立的 MCP 网络服务？
mcp.NewInMemoryTransports() 将 MCP 服务与 tunnelclient.New 放在同一进程中，无需绑定端口或使用 stdio。