Secure MCP Tunnel | OpenAI API

来源: https://developers.openai.com/api/docs/guides/secure-mcp-tunnels 抓取时间: 2026-07-21 16:26:49

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

什么是 MCP 隧道？

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

Secure MCP Tunnel 保持 MCP 服务器的私有性，同时为受支持的 OpenAI 产品提供正常的 MCP 请求路径。tunnel-client 向 OpenAI 轮询工作，在本地转发 MCP 请求，并通过同一隧道返回响应。

何时使用 Secure MCP Tunnel

• 您的 MCP 服务器运行在私有网络、本地环境、开发人员机器上，或位于现有访问控制之后。
• 您希望 ChatGPT、Codex、Responses API 或其他受支持的 OpenAI 产品使用该服务器，而不将 MCP 服务器公开。
• 您的网络允许运行 tunnel-client 的主机默认向 api.openai.com:443 发出出站 HTTPS 请求，或在配置了控制平面 mTLS 时向 mtls.api.openai.com:443 发出请求，并能够访问私有 MCP 服务器。
• 首先阅读 MCP 和连接器指南 了解一般 MCP 概念。

工作原理

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

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

OpenAI 产品调用 OpenAI 托管的隧道端点；tunnel-client 进行长轮询获取排队的工作并通过同一隧道返回 MCP 响应。

开始之前

您需要：

• 来自 Platform 隧道设置 的 tunnel_id。
• 用于 tunnel-client 的运行时 API 密钥。
• tunnel-client 可以通过 stdio 或 HTTP 从您的网络内访问的 MCP 服务器。

权限和访问

Platform 隧道权限 和 ChatGPT 开发者模式访问是分开的：

• 创建或编辑隧道需要隧道读取 + 管理权限。
• 运行 tunnel-client 或在创建应用时选择隧道需要隧道读取 + 使用权限。
• 隧道权限适用于 Platform 组织。Platform 组织所有者或 RBAC 管理员授予隧道角色。
• ChatGPT 开发者模式是单独的工作区权限。对于企业版/教育版，工作区管理员授予开发者模式访问权限；然后用户在设置 → 安全和登录中启用。请参阅开发者模式帮助中心文章了解计划特定的策略。

请向目标 ChatGPT 工作区管理员申请开发者模式访问权限，并向目标 Platform 组织所有者/RBAC 管理员申请隧道权限。

将隧道与正确的组织和工作区关联

隧道可以与一个或多个 Platform 组织或 ChatGPT 工作区关联。使用这些关联来定义应允许查找或使用隧道的每个 OpenAI 上下文。

• 包含拥有或管理隧道的 Platform 组织。
• 包含在创建应用时应列出隧道的 ChatGPT 工作区。
• 当 Codex、Responses API 或其他受支持的产品将从该组织调用私有 MCP 服务器时，包含另一个 Platform 组织。
• 对 tunnel-client 使用相同的 tunnel_id；添加组织或工作区不会创建第二个隧道或更改私有 MCP 服务器端点。

对于个人账户，请使用属于该账户的个人 Platform 组织。对于 ChatGPT 和 Codex 测试，请将隧道与目标 ChatGPT 工作区和 Codex 将使用的 Platform 组织关联。仅与个人 Platform 组织关联的隧道不会自动出现在企业版/教育版工作区中。

如果 Platform 组织和 ChatGPT 工作区已链接，您可以在 Platform 隧道设置中添加缺失的组织或工作区。如果您的企业设置无法自动验证，例如当 Platform 组织没有对应的 ChatGPT 工作区时，请联系您的 OpenAI 客户团队，请求对应使用隧道的企业账户映射进行审查的手动关联覆盖。

网络要求

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

设置 tunnel-client

打开 Platform 隧道设置，然后使用那里的下载链接或来自 openai/tunnel-client 的最新公共 tunnel-client 版本。让您的运行手册指向最新版本 URL，而不是硬编码特定版本的 URL。

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

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 工具调用依赖于运行中的客户端。

位于 /ui 的本地管理 UI 会显示运行中的客户端在从 ChatGPT、Codex 或 API 流程测试之前是否健康、就绪和已连接。

选择在哪里运行 tunnel-client

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

• Kubernetes 边车（sidecar）： 在一个 Pod 中与 MCP 服务器并排运行 tunnel-client，通过 localhost 连接。
• 专用 Kubernetes 部署： 当 MCP 服务器已经可以通过私有 Service 访问时，单独运行 tunnel-client。
• VM 或 systemd 服务： 在可以通过私有网络访问 MCP 服务器的主机上运行 tunnel-client。

从 ChatGPT 连接

打开设置 → 插件或访问 chatgpt.com/plugins，选择加号按钮创建开发者模式应用，并在连接下选择隧道。当 ChatGPT 列出可用隧道时选择一个，或者如果您已经有有效的 tunnel_id 也可以粘贴它。

如果隧道没有出现在 ChatGPT 中，请验证隧道是否与目标 ChatGPT 工作区关联（而不仅仅是与 Platform 组织关联），以及应用创建者是否具有隧道读取 + 使用权限。

安全和网络

私有 MCP 服务器保留在客户控制的环境内。tunnel-client 使用运行时 API 密钥以及可选的控制平面 mTLS（需要时）通过出站 HTTPS 访问 OpenAI。

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

日志边界

Secure MCP Tunnel 将隧道传输与应用级产品日志分开：

• 隧道控制平面身份验证、长轮询/响应流量和单独的隧道传输请求不会通过隧道路径作为 ChatGPT 合规平台应用事件发出。
• 隧道元数据更改通过 API Platform 审计日志 界面暴露为 tunnel.created、tunnel.updated 和 tunnel.deleted。
• 当 ChatGPT 通过 Secure MCP Tunnel 访问自定义应用时，隧道仍然只是传输路径。正常的应用级合规日志记录仍在应用路径上应用，包括应用调用日志和应用身份验证生命周期日志，如应用链接或取消链接时的 APP_AUTH_LOG。

高级：白名单 HTTP 调用

Secure MCP Tunnel 还可以支持从受支持的智能体或 API 流程到客户网络的范围有限的 HTTP 调用。tunnel-client 包含一个嵌入式 MCP 服务器 Harpoon，它按标签暴露配置的 HTTP 目标，并允许调用者通过隧道使用有界的请求/响应限制调用它们。

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

故障排除

• Platform 隧道设置中显示"需要隧道访问"： 隧道权限是组织级别的，而不是项目级别的。选择预期的 Platform 组织，然后要求组织所有者或 RBAC 管理员将您添加到具有读取权限的角色或组中以查看隧道，或添加到具有读取 + 管理权限的角色中以创建、编辑或删除隧道。如果不存在匹配的角色，他们可以创建一个角色，将其分配给一个组，然后将您添加到该组中。您还需要使用权限来运行 tunnel-client 或在连接器设置中选择隧道。新角色分配最多可能需要 30 分钟才能传播。
• 隧道在 ChatGPT 中不可见： 检查隧道是否包含目标 ChatGPT 工作区，而不仅仅是 Platform 组织；然后检查连接器操作员的隧道使用权限。如果工作区无法自动链接到企业账户，请联系您的 OpenAI 客户团队进行审查的手动关联覆盖。
• 连接器发现或工具调用失败： 确认 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 流程仍可能失败。

在哪里配置

• 在 Platform 隧道设置 中管理 OpenAI 托管的 MCP 隧道端点。
• 从设置 → 插件或 chatgpt.com/plugins 创建开发者模式应用时使用隧道。
• 对于 Codex 或 API 流程，请使用受支持的产品界面暴露的隧道支持的 MCP 目标。

后续步骤

• 在 Platform 隧道设置 中创建或管理隧道。
• 使用 tunnel-client doctor --profile <profile> --explain 验证您的 tunnel-client 配置。
• 从设置 → 插件、chatgpt.com/plugins 或您正在使用的受支持 OpenAI 界面连接隧道。

从 Platform 隧道设置创建和管理 OpenAI 托管的 MCP 隧道端点。

将 ChatGPT 开发者模式应用连接到私有 MCP 服务器时选择隧道。