安全 MCP 隧道

安全 MCP 隧道可让您将私有 MCP 服务器连接到受支持的 OpenAI 产品，而无需开放入站防火墙端口或将这些服务器暴露给公共互联网。在 tunnel-client 能够访问您的 MCP 服务器的网络内部运行该命令；它会建立一条到 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 和连接器指南 for general MCP concepts.

工作原理

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

私有 MCP 服务器不需要公共监听器。OpenAI 托管的端点为受支持的产品提供标准的 MCP 请求路径，而网络发起点始终留在您的边界内。当连接器请求流式结果时，隧道路径可以转发中间的服务器发送事件。

准备工作

您需要：

• A tunnel_id from 平台隧道设置.
• 运行时 API 密钥，用于 tunnel-client。关键主体需要隧道 阅读 + 使用 for the target tunnel.
• 带 Tunnels 的隧道管理器 阅读 + 管理 如果您需要创建或编辑隧道元数据。
• An MCP server that tunnel-client 可以通过网络内的 stdio 或 HTTP 访问。

网络要求

tunnel-client 不需要入站互联网访问。它需要到 OpenAI 的出站 HTTPS 连接，以及与私有 MCP 服务器的本地可达性：

设置 tunnel-client

打开 平台隧道设置，然后使用那里的下载链接或最新的公开 tunnel-client 发布于 openai/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 的位置

在 Agent Builder 内部运行 tunnel-client 应位于已经能够访问私有 MCP 服务器的同一信任边界内。常见的部署模式有：

• Kubernetes sidecar： 在 Agent Builder 内部运行 tunnel-client 在同一个 Pod 中与 MCP server 并排运行，并通过以下方式连接： localhost.
• 专用 Kubernetes 部署： 在 Agent Builder 内部运行 tunnel-client 在 MCP server 已可通过私有 Service 访问时进行单独部署。
• VM 或 systemd 服务： 在 Agent Builder 内部运行 tunnel-client 部署在可以通过私有网络访问 MCP server 的主机上。

从 ChatGPT 连接

打开 ChatGPT connector 设置，创建一个自定义连接器，并选择 隧道 下 连接。当 ChatGPT 列出隧道时，选择一个可用的隧道，或者粘贴一个有效的 tunnel_id 如果您已经有的话。

如果隧道未在 ChatGPT 中显示，请验证该隧道是否已关联到目标工作区，并且连接器操作员是否具有 Tunnels 阅读 + 使用.

安全与网络

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

高级：已允许列表的 HTTP 调用

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

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

故障排除

• 隧道在 ChatGPT 中不可见： 检查隧道的工作区范围以及连接器操作员的 Tunnels 使用 permission.
• 连接器发现或工具调用失败： 确认 tunnel-client run ... 仍在运行，然后重新运行 tunnel-client doctor --profile <name> --explain.
• 您可以检查隧道，但无法编辑它： 操作员可能具有 Tunnels 阅读 但不具有 Tunnels 管理.
• tunnel-client 公开 /healthz, /readyz, /metrics，以及位于以下地址的本地管理 UI： /ui.
• 管理界面默认仅限环回访问。仅在您有意需要操作员网络访问该界面时才远程公开它。
• 使用这些界面来确认客户端运行正常、已准备就绪且正在轮询，然后再从 ChatGPT、Codex 或 API 流程中进行测试。
• 如果客户端未连接，通过隧道的请求将失败，直到 tunnel-client reconnects.
• 原始 HTTP 日志记录默认处于禁用状态，并且支持导出的内容会经过脱敏处理。

OAuth

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

配置位置

• 在以下位置管理 OpenAI 托管的 MCP 隧道端点： 平台隧道设置.
• 在通过以下方式创建连接器时使用隧道 ChatGPT connector 设置.
• 对于 Codex 或 API 流程，请使用受支持的产品界面提供的隧道支持的 MCP 目标。

后续步骤

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