OpenAI 安全 MCP 隧道

安全MCP隧道（Secure MCP Tunnel）让受支持的OpenAI产品连接私有MCP服务器，无须开放防火墙入站端口，也无须将服务器暴露到公网。在已经能够访问MCP服务器的网络内部运行tunnel-client：它向OpenAI建立出站HTTPS路径、拉取排队任务、在本地转发请求，再沿同一隧道返回响应。

安全MCP隧道支持私有MCP连接，包括自定义服务器测试，不支持公开插件提交或分发。公开插件要求稳定、可从公网访问的HTTPS MCP端点。如果服务器必须保持私有，可提供公开HTTPS代理，将请求转发到私有服务器。端点和认证要求见公开插件提交。

什么是MCP隧道

MCP隧道是网络内部主机向OpenAI托管MCP端点建立的仅出站连接。服务器部署于私网、本地机房或防火墙后，但ChatGPT、Codex、Responses API或其他受支持产品需要调用它时，可使用此方式。

安全隧道保持MCP服务器私有，同时为产品提供常规MCP请求路径。tunnel-client向OpenAI轮询任务，在本地转发MCP请求，再返回响应。

适用场景

• MCP服务器运行于私网、本地机房、开发者机器，或已有访问控制之后。
• 希望ChatGPT、Codex、Responses API或其他受支持产品使用该服务器，而不公开服务器。
• 运行tunnel-client的主机默认可出站访问api.openai.com:443；配置控制平面mTLS时，可访问mtls.api.openai.com:443；同时能够访问私有MCP服务器。
• MCP基础概念可先阅读MCP服务器指南。

工作原理

1. 在Platform隧道设置中创建或管理OpenAI托管MCP隧道端点。
2. 在可访问私有MCP服务器的网络中运行tunnel-client。
3. 为客户端配置隧道身份及私有服务器地址。
4. OpenAI产品向托管隧道端点发送MCP请求。
5. 客户端长轮询排队任务，将每个JSON-RPC请求转发到私有服务器，再通过隧道回传响应。

私有服务器无须公开监听。托管端点提供常规请求路径，而网络连接从你的边界内部发起。连接器要求流式结果时，隧道可以转发中间的服务器发送事件。

OpenAI产品调用托管隧道端点；客户端长轮询任务，并沿同一隧道返回MCP响应。

开始之前

你需要：

• 从Platform隧道设置取得tunnel_id。
• 供tunnel-client使用的运行时API密钥。
• 客户端可在内网通过stdio或HTTP访问的MCP服务器。

权限与访问

Platform隧道权限与ChatGPT自定义MCP服务器访问权限是两套独立权限：

• 创建或编辑隧道需要Tunnels的 Read（读取）+ Manage（管理）权限。
• 运行客户端，或创建应用时选择隧道，需要 Read（读取）+ Use（使用）权限。
• 隧道权限属于Platform组织，由组织所有者或RBAC管理员授予相应角色。
• ChatGPT内添加和使用自定义服务器仍受工作区权限与安全限制约束，见添加自定义MCP服务器。

分别向目标ChatGPT工作区管理员申请添加与使用自定义服务器的权限，向目标Platform组织所有者或RBAC管理员申请隧道权限。

关联正确的组织与工作区

一个隧道可以关联多个Platform组织或ChatGPT工作区，以明确哪些OpenAI上下文可以发现或使用它：

• 包含拥有或管理该隧道的Platform组织。
• 包含应在创建应用时列出该隧道的ChatGPT工作区。
• 如果Codex、Responses API或其他产品从另一个Platform组织调用私有服务器，也应关联那个组织。
• 客户端继续使用相同tunnel_id；添加组织或工作区不会创建第二条隧道，也不会改变私有服务器端点。

个人账户使用归属于该账户的个人Platform组织。测试ChatGPT和Codex时，关联目标ChatGPT工作区及Codex使用的Platform组织。只关联个人Platform组织的隧道，不会自动出现在Enterprise/Edu工作区。

如果组织和工作区已经关联，可在Platform隧道设置补充缺失关联。如果企业设置无法自动核实，例如Platform组织没有对应ChatGPT工作区，应联系OpenAI客户团队，为需要使用隧道的企业账户映射申请经过审核的人工关联覆盖。

网络要求

客户端无须入站互联网访问，只需要出站HTTPS和私有服务器的本地可达性：

限制

隧道创建和连接器MCP流量适用以下默认限制：

这些是服务保护限制，不是吞吐量或延迟保证。为清理而保留队列记录，不会延长120秒截止时间。如需提高隧道数量或流量限制，请联系OpenAI支持。

配置tunnel-client

打开Platform隧道设置，使用其中下载链接，或下载openai/tunnel-client最新公开版本。运维手册应指向最新版本入口，而非硬编码特定发布地址。

已有二进制文件时，先运行tunnel-client help quickstart。配置命名的本地stdio配置档案可使用：

来源示例 1（bash）：

## [中文] 设置控制平面密钥引用，初始化指定隧道和stdio配置档案，诊断后持续运行客户端；替换示例ID、路径及密钥，不把真实机密放入聊天或版本库。
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-command替换为--mcp-server-url https://mcp.internal.example.com/mcp。

创建或测试应用期间，保持tunnel-client run ...健康运行；应用发现和工具调用依赖该客户端。

在ChatGPT、Codex或API流程中测试前，可通过本地/ui确认客户端健康、就绪且已连接。

选择客户端运行位置

在已经能访问私有服务器的同一信任边界内运行客户端。常见部署方式：

• Kubernetes边车容器：与MCP服务器位于同一Pod，通过localhost连接。
• 独立Kubernetes部署：服务器已能通过私有Service访问时，单独运行客户端。
• 虚拟机或systemd服务：部署到能通过私网访问MCP服务器的主机。

从ChatGPT连接

进入ChatGPT Plugins，选择加号和“添加自定义MCP服务器”，在Connection中选择Tunnel。选择列表中的可用隧道，或粘贴已有的有效tunnel_id。配置认证，检查风险提示，选择“我已了解并希望继续”，再创建为插件。

隧道没有出现在ChatGPT中时，确认它关联了目标工作区，而不只是Platform组织；同时确认创建者具有Tunnels的Read+Use权限。

使用Codex配置并验证

如果希望由Codex引导配置，为其提供Platform和ChatGPT的浏览器访问能力，以及能访问私有服务器的主机终端。将以下提示词粘贴到Codex：

来源示例 2（text）：

中文译释：供粘贴到Codex对话的提示词完整译文，原文命令、地址和权限名称保留，不在本次制作中执行：

帮我端到端配置并验证一条从内网MCP服务器到ChatGPT的私有安全MCP隧道。使用浏览器/计算机和终端，遵循https://developers.openai.com/api/docs/guides/secure-mcp-tunnels及https://github.com/openai/tunnel-client/blob/master/docs/onboarding.md，过程中检查当前界面和命令行帮助。

先确定目标Platform组织、ChatGPT工作区、MCP服务器HTTP地址或stdio命令，以及客户端主机。检查已有隧道、密钥和ChatGPT自定义MCP插件，复用合适资源。确认组织/工作区关联和权限：创建者需要Tunnels Read+Manage，受限运行时密钥及插件操作者需要Read+Use。

不要将明文机密放进聊天、命令参数、日志、截图或配置文件；让我通过安全输入或环境变量引用在本地提供。安装受支持的tunnel-client，运行tunnel-client help quickstart、配置服务器、运行tunnel-client doctor --profile <name& --explain、启动客户端，确认就绪且正在轮询。在发现和调用期间持续运行。

在ChatGPT Plugins中添加或完成私有自定义MCP服务器，Connection选择Tunnel，选同一条隧道，配置认证，执行一个安全且有代表性的工具调用。为每个检查点报告实际证据；存在阻碍时报告准确错误和下一步。只有ChatGPT工具调用成功后，才将配置标为完成。

Help me set up and verify a private Secure MCP Tunnel from my internal MCP
server to ChatGPT end to end. Use browser/computer access and a terminal,
following https://developers.openai.com/api/docs/guides/secure-mcp-tunnels
and https://github.com/openai/tunnel-client/blob/master/docs/onboarding.md;
check the current UI and CLI help as you go.

First identify the intended Platform organization and ChatGPT workspace, MCP
server HTTP URL or stdio command, and client host. Inspect any existing tunnel,
key, and ChatGPT custom MCP plugin; reuse suitable resources. Confirm the
tunnel's organization and workspace association and permissions: tunnel
creators need Tunnels Read + Manage; the restricted runtime key and plugin
operator need Tunnels Read + Use.

Keep literal secrets out of chat, command arguments, logs, screenshots, and
config files. Have me enter them locally through a secure input or environment
reference. Install the supported tunnel-client; run
`tunnel-client help quickstart`, configure the server, run
`tunnel-client doctor --profile <name> --explain`, start the client, and
verify readiness and active polling. Keep it running for discovery and calls.

In ChatGPT Plugins, add or finish a private custom MCP server with
Connection: Tunnel, select the same tunnel, configure required authentication,
and make a safe representative tool call. Report observed evidence for each
checkpoint and the exact error and next action for any blocker. Call setup
complete only after the ChatGPT tool call succeeds.

从Responses API连接

在MCP工具定义中使用tunnel_id传入隧道标识。不要将OpenAI托管隧道端点填入server_url；该字段仅用于Responses API可直接访问的MCP服务器。

通过Responses API使用安全MCP隧道：

来源示例 3（bash）：

请求中的input提示词译文：

使用私有MCP服务器回答我的请求。

## [中文] 向Responses API声明私有MCP隧道工具，使用tunnel_id而非server_url；实际调用仍受认证、隧道权限和工具确认设置约束。
curl https://api.openai.com/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "model": "gpt-6-astra",
    "input": "Use the private MCP server to answer my request.",
    "tools": [
      {
        "type": "mcp",
        "server_label": "private_mcp",
        "tunnel_id": "tunnel_0123456789abcdef0123456789abcdef"
      }
    ]
  }'

安全与网络

私有服务器留在客户控制的环境中。客户端使用运行时API密钥，通过出站HTTPS连接OpenAI，需要时另配置控制平面mTLS。

• MCP服务器地址保持私有，仅在客户端运行环境内部使用。
• 客户端向OpenAI隧道控制平面认证；受支持的OpenAI产品使用托管端点。
• 隧道访问遵循现有组织与工作区上下文，不额外引入公开入口。
• 客户端支持出站代理、自定义CA证书包、控制平面客户端证书，以及MCP侧mTLS等企业网络要求。

日志边界

安全MCP隧道区分隧道传输日志和应用级产品日志：

• 隧道控制平面认证、长轮询/响应流量及各次传输请求，不会由隧道路径生成ChatGPT Compliance Platform应用事件。
• 隧道元数据变更通过API Platform审计日志记录为tunnel.created、tunnel.updated、tunnel.deleted。
• ChatGPT经隧道访问自定义应用时，隧道只是传输路径，常规应用级合规日志仍适用，包括应用调用日志和连接/断开应用时的APP_AUTH_LOG等认证生命周期日志。

进阶：允许列表HTTP调用

安全MCP隧道还支持受支持的智能体或API流程向客户内网发起范围狭窄的HTTP调用。客户端内置名为Harpoon的MCP服务器，通过标签暴露配置的HTTP目标，让调用方在受限请求/响应范围内访问。

适用于无需公开少量私有REST端点、但仍需访问它们的场景。Harpoon不是通用代理：调用方不能任意选择主机，只能使用客户配置的目标和方法。

排错

• 设置页显示“Tunnels access required”：权限属于组织，而非项目。先选择目标Platform组织，请所有者或RBAC管理员授予Read以查看，或Read+Manage以创建、编辑和删除。没有合适角色时，可创建角色、分配给群组，再将用户加入。运行客户端或在连接器中选隧道还需要Use。新角色分配最多可能需30分钟传播。
• ChatGPT中看不到隧道：确认关联目标ChatGPT工作区，再检查操作者的Use权限。企业工作区无法自动关联时，联系客户团队申请经过审核的人工关联覆盖。
• 连接器发现或调用失败：确认客户端仍在运行，再执行tunnel-client doctor --profile <name> --explain。
• 可以查看但不能编辑：操作者可能只有Read而没有Manage。
• 客户端提供/healthz、/readyz、/metrics及本地管理界面/ui。
• 管理界面默认仅监听回环地址，只有明确需要运维网络访问时才远程暴露。
• 在产品侧测试前，通过这些入口确认客户端健康、就绪且正在轮询。
• 客户端断开期间，经隧道的请求会失败，直到重连。
• 原始HTTP日志默认关闭，支持导出会做脱敏。

OAuth

• OAuth发现请求可以走隧道，因此MCP服务器本身可以保持私有。
• 隧道保留面向浏览器的OAuth流程所需的上游授权服务器元数据。
• 授权服务器本身不会自动被隧道转发。如果它从公网及客户端主机都无法访问，即使MCP服务器可达，OAuth也可能失败。

配置入口

• 在Platform隧道设置管理OpenAI托管MCP隧道端点。
• 在ChatGPT Plugins添加自定义MCP服务器时使用隧道。
• Codex或API流程使用受支持产品界面提供的隧道MCP目标。

后续操作

• 在Platform隧道设置创建或管理隧道。
• 使用tunnel-client doctor --profile <profile> --explain验证配置档案。
• 从ChatGPT Plugins或正在使用的受支持产品连接。

在Platform隧道设置中创建和管理托管端点。