安全 MCP 隧道

安全 MCP 隧道（Secure MCP Tunnel）让您能够将私有 MCP 服务器连接到支持的 OpenAI 产品，而无需打开入站防火墙端口或将这些服务器暴露在公共互联网上。在能够访问您 MCP 服务器的网络内部运行 tunnel-client；它会打开一条通往 OpenAI 的出站 HTTPS 路径，拉取队列中的 MCP 任务，在本地转发请求，并通过同一隧道返回响应。

什么是 MCP 隧道？

MCP 隧道是从您网络内部的主机到 OpenAI 托管的 MCP 端点之间的仅出站连接。当您的 MCP 服务器是私有的、位于本地环境或位于防火墙后，但 ChatGPT、Codex、Responses API 或其他支持的 OpenAI 界面仍需要调用它时，请使用此功能。

安全 MCP 隧道在保持 MCP 服务器私有的同时，为支持的 OpenAI 产品提供了正常的 MCP 请求路径。tunnel-client 会轮询 OpenAI 获取任务，在本地转发 MCP 请求，并通过同一隧道返回响应。

何时使用安全 MCP 隧道

• 您的 MCP 服务器运行在私有网络、本地环境、开发者机器上或现有的访问控制策略之后。
• 您希望 ChatGPT、Codex、Responses API 或其他支持的 OpenAI 界面使用该服务器，而无需将 MCP 服务器公开。
• 您的网络允许运行 tunnel-client 的主机默认向 api.openai.com:443 发起出站 HTTPS 请求（配置控制平面 mTLS 时为 mtls.api.openai.com:443），并能访问私有 MCP 服务器。
• 请先阅读 MCP 和连接器指南以了解常规 MCP 概念。

它是如何工作的

1. 在平台隧道设置中创建或管理 OpenAI 托管的 MCP 隧道端点。
2. 在能够访问私有 MCP 服务器的网络内运行 tunnel-client。
3. 使用隧道标识和私有 MCP 服务器地址配置 tunnel-client。
4. OpenAI 产品将 MCP 请求发送到 OpenAI 托管的隧道端点。
5. tunnel-client 长轮询队列中的任务，将每个 JSON-RPC 请求转发给私有 MCP 服务器，并将响应通过隧道发回。

私有 MCP 服务器无需公共监听器。OpenAI 托管的端点为支持的产品提供了正常的 MCP 请求路径，而网络发起点保留在您的边界内。当连接器请求流式结果时，隧道路径可以转发中间的服务器发送事件（SSE）。

开始之前

您需要

• 从 平台隧道设置 获取的 tunnel_id。
• tunnel-client 的运行时 API 密钥。密钥主体需要对目标隧道拥有“隧道 读取 + 使用”权限。
• 如果您需要创建或编辑隧道元数据，则需要拥有“隧道 读取 + 管理”权限的隧道管理器。
• 一个 tunnel-client 可以从您的网络内部通过 stdio 或 HTTP 访问的 MCP 服务器。

网络要求

tunnel-client 不需要入站互联网访问。它需要通往 OpenAI 的出站 HTTPS 以及对私有 MCP 服务器的本地可达性。

设置 tunnel-client

打开 平台隧道设置，使用其中的下载链接或从 openai/tunnel-client 获取最新的公开 tunnel-client 版本。请确保您的运行手册指向最新版本 URL，而不是硬编码特定的发行版 URL。

如果您已有二进制文件，请从 tunnel-client help quickstart 开始。对于指定的本地 stdio 配置文件，请使用：

1
2
3
4
5
6
7
8
9
10
export CONTROL_PLANE_API_KEY="sk-..."

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

对于 HTTP MCP 服务器，使用 --mcp-server-url https://mcp.internal.example.com/mcp 代替 --mcp-command。

在创建或测试连接器时，请保持 tunnel-client run ... 处于运行状态。连接器发现和 MCP 工具调用依赖于运行中的客户端。

选择运行 tunnel-client 的位置

在能够访问私有 MCP 服务器的同一信任边界内运行 tunnel-client。常见的部署模式包括：

• Kubernetes Sidecar： 在同一个 Pod 中与 MCP 服务器一起运行 tunnel-client，并通过 localhost 连接。
• 专用 Kubernetes 部署： 当 MCP 服务器已可通过私有 Service 访问时，单独运行 tunnel-client。
• VM 或 systemd 服务： 在能够通过私有网络访问 MCP 服务器的主机上运行 tunnel-client。

从 ChatGPT 连接

打开 ChatGPT 连接器设置，创建一个自定义连接器，并在“连接”下选择“隧道”。当 ChatGPT 列出可用隧道时选择它，或者在您已有 tunnel_id 时直接粘贴。

如果隧道未出现在 ChatGPT 中，请验证隧道是否与目标工作区关联，并且连接器操作员是否具有“隧道 读取 + 使用”权限。

安全与网络

• MCP 服务器地址保持私有，仅在 tunnel-client 运行的环境内部使用。
• tunnel-client 向 OpenAI 隧道控制平面进行身份验证；支持的 OpenAI 产品使用 OpenAI 托管的隧道端点。
• 隧道访问遵循现有的组织和工作区上下文，而不是引入单独的公共入口路径。
• tunnel-client 支持出站代理、自定义 CA 证书包、控制平面客户端证书和 MCP 端 mTLS 等企业网络要求。

高级：允许的 HTTP 调用

安全 MCP 隧道还可以支持从受支持的 Agent 或 API 流程向客户网络发起的窄范围 HTTP 调用。tunnel-client 包含一个嵌入式 MCP 服务器 Harpoon，它通过标签暴露配置的 HTTP 目标，并允许调用者在受限的请求/响应限制内通过隧道进行调用。

当您需要访问一小部分私有 REST 端点而无需将其公开时，请使用此功能。Harpoon 不是通用代理：调用者不能选择任意主机，且请求仅限于客户配置的目标和方法。

故障排除

• 在 ChatGPT 中看不到隧道： 检查隧道工作区范围和连接器操作员的“隧道 使用”权限。
• 连接器发现或工具调用失败： 确认 tunnel-client run ... 仍在运行，然后重新运行 tunnel-client doctor --profile <name> --explain。
• 可以检查隧道但无法编辑它： 操作员可能只有“隧道 读取”权限，而没有“隧道 管理”权限。
• tunnel-client 暴露了 /healthz、/readyz、/metrics 以及位于 /ui 的本地管理 UI。
• 管理 UI 默认仅限回环地址（loopback）。仅在需要操作员网络访问它时才将其远程公开。
• 在从 ChatGPT、Codex 或 API 流程进行测试之前，请使用这些界面确认客户端是否健康、就绪且正在轮询。
• 如果客户端未连接，通过隧道的请求将失败，直到 tunnel-client 重新连接。
• 原始 HTTP 日志默认禁用，支持导出文件中的信息经过脱敏处理。

OAuth

• OAuth 发现过程可以通过隧道路径传输，因此 MCP 服务器本身可以保持私有。
• 隧道保留了浏览器端 OAuth 流程所需的上游授权服务器元数据。
• 授权服务器本身不会自动通过隧道传输。如果它在公共互联网和 tunnel-client 主机上均不可访问，即使 MCP 服务器可达，OAuth 流程也可能失败。

配置位置

• 在 平台隧道设置 中管理 OpenAI 托管的 MCP 隧道端点。
• 在创建 ChatGPT 连接器 时使用隧道。
• 对于 Codex 或 API 流程，使用由受支持的产品界面暴露的隧道支持的 MCP 目标。

后续步骤

• 在 平台隧道设置 中创建或管理隧道。
• 使用 tunnel-client doctor --profile <profile> --explain 验证您的 tunnel-client 配置文件。
• 从 ChatGPT 连接器设置 或您正在使用的受支持 OpenAI 界面连接隧道。