使用安全 MCP 隧道,您可以将私有 MCP 服务器连接到支持此功能的 OpenAI 产品,无需开放防火墙入站端口,也无需向公网开放这些服务器。在能够访问 MCP 服务器的网络内运行 tunnel-client。它会向 OpenAI 发起出站 HTTPS 连接,拉取队列中的 MCP 任务,在本地转发请求,并通过同一条隧道返回响应。
安全 MCP 隧道支持私有 MCP 连接,可用于测试自定义 MCP 服务器。它不支持提交或分发公开插件。 公开插件需要稳定且可从公网访问的 HTTPS MCP 端点。如果 MCP 服务器必须保持私有,请提供一个可从公网访问的 HTTPS 代理,由代理将请求转发给服务器。有关端点和身份验证要求,请参阅提交公开插件。
什么是 MCP 隧道?
MCP 隧道是一种仅由您网络内的主机向 OpenAI 托管的 MCP 端点发起的连接。如果您的 MCP 服务器位于私有网络中、部署在本地或位于防火墙后方,而 ChatGPT、Codex、Responses API 或其他支持此功能的 OpenAI 产品仍需调用该服务器,就可以使用 MCP 隧道。
安全 MCP 隧道让 MCP 服务器保持私有,同时让支持此功能的 OpenAI 产品按常规方式发送 MCP 请求。tunnel-client 通过轮询从 OpenAI 获取任务,在本地转发 MCP 请求,再通过同一条隧道返回响应。
何时使用安全 MCP 隧道
- 您的 MCP 服务器在私有网络、本地设施或开发者的计算机上运行,或受现有访问控制措施保护。
- 您希望 ChatGPT、Codex、Responses API 或其他支持此功能的 OpenAI 产品使用该服务器,同时保持 MCP 服务器私有。
- 您的网络允许运行
tunnel-client的主机访问私有 MCP 服务器,并向api.openai.com:443(默认)或mtls.api.openai.com:443(已配置控制平面 mTLS 时)发送出站 HTTPS 请求。 - 如需了解 MCP 的基本概念,请先阅读 MCP 服务器指南。
工作原理
- 在平台的隧道设置中创建或管理由 OpenAI 托管的 MCP 隧道端点。
- 在能够访问私有 MCP 服务器的网络内运行
tunnel-client。 - 为
tunnel-client配置隧道身份信息和私有 MCP 服务器地址。 - OpenAI 产品将 MCP 请求发送到 OpenAI 托管的隧道端点。
tunnel-client通过长轮询获取队列中的任务,将每个JSON-RPC请求转发到私有 MCP 服务器,再通过隧道回传响应。
私有 MCP 服务器无需监听公网请求。通过 OpenAI 托管的端点,支持此功能的产品可以按常规方式发送 MCP 请求,而网络连接始终由您网络边界内的主机发起。如果连接器请求流式结果,隧道还可以转发服务器在处理过程中推送的事件。
OpenAI 产品调用 OpenAI 托管的隧道端点。tunnel-client 通过长轮询获取队列中的任务,再通过同一条隧道返回 MCP 响应。
准备工作
您需要准备:
- 一个
tunnel_id,可从平台隧道设置获取。 - 供
tunnel-client运行时使用的 API 密钥。 - 一台 MCP 服务器,
tunnel-client可以从您的网络内部通过 stdio 或 HTTP 访问它。
权限与访问控制
平台隧道权限与 ChatGPT 自定义 MCP 服务器的访问权限分别管理:
- 创建或编辑隧道需要隧道的读取和管理权限。
- 运行
tunnel-client或在创建应用时选择隧道,需要隧道的读取和使用权限。 - 隧道权限适用于平台组织。平台组织所有者或 RBAC 管理员负责分配隧道角色。
- 在 ChatGPT 中添加和使用自定义 MCP 服务器仍受工作空间权限和安全限制约束。请参阅添加自定义 MCP 服务器。
请向目标 ChatGPT 工作空间的管理员申请添加和使用自定义 MCP 服务器的权限,并向目标平台组织的所有者或 RBAC 管理员申请隧道权限。
将隧道与相应的组织和工作空间关联
一条隧道可以关联一个或多个平台组织或 ChatGPT 工作空间。通过这些关联,您可以指定允许查找或使用隧道的所有 OpenAI 组织和工作空间。
- 关联拥有或管理隧道的平台组织。
- 关联需要在创建应用时列出该隧道的 ChatGPT 工作空间。
- 如果 Codex、Responses API 或其他支持此功能的产品将从另一个平台组织调用私有 MCP 服务器,也请关联该组织。
- 使用同一个
tunnel_id运行tunnel-client。添加组织或工作空间不会创建第二条隧道,也不会更改私有 MCP 服务器端点。
对于个人账号,请使用该账号所属的个人平台组织。如需使用 ChatGPT 和 Codex 进行测试,请将隧道与目标 ChatGPT 工作空间以及 Codex 将使用的平台组织关联。仅与个人平台组织关联的隧道不会自动出现在 Enterprise 或 Edu 工作空间中。
如果平台组织与 ChatGPT 工作空间已建立关联,您可以在平台隧道设置中为隧道补充尚未添加的组织或工作空间。如果系统无法自动验证您的企业配置(例如,平台组织没有对应的 ChatGPT 工作空间),请联系您的 OpenAI 客户团队,请其审核并手动指定应使用该隧道的企业账号关联关系。
网络要求
tunnel-client 无需接受来自互联网的入站连接。它需要能够通过出站 HTTPS 连接访问 OpenAI,并在本地访问私有 MCP 服务器:
| 来源 | 目标 | 用途 |
|---|---|---|
运行 tunnel-client 的主机 |
通过 HTTPS 访问 api.openai.com:443 的 /v1/tunnel/* 路径 |
默认用于轮询和回传响应。 |
运行 tunnel-client 的主机 |
通过 HTTPS 访问 mtls.api.openai.com:443 的 /v1/tunnel/* 路径 |
配置控制平面 mTLS 后用于轮询和回传响应。 |
运行 tunnel-client 的主机 |
已配置的 stdio 命令或 MCP 服务器 URL | 从您的网络内部转发 MCP 请求。 |
限制
安全 MCP 隧道对隧道创建和连接器的 MCP 流量采用以下默认限制:
| 限制项 | 默认值 | 适用范围 |
|---|---|---|
| 隧道数量 | 每个 ChatGPT 工作空间 1,000 条,每个平台组织 1,000 条 | 每条隧道都计入与之关联的每个工作空间和平台组织的创建配额。 |
| MCP 请求速率 | 每分钟 600 个请求(持续速率为每秒 10 个) | 在所有 MCP 通道中,隧道 ID 和调用方应用 ID 均相同的请求共享此配额。如果无法获取调用方应用 ID,则同一用户使用同一隧道 ID 的请求共享配额。运行多个 tunnel-client 进程不会增加配额。 |
| 序列化后的请求或响应大小 | 10 MiB(10,485,760 字节) | 限制适用于序列化后的整个隧道消息封装,包括标头和协议元数据,因此实际可容纳的 MCP 内容略少。服务对每条流式通知和最终响应分别应用此限制。 |
| 请求时限 | 120 秒 | 从请求进入托管队列到最终响应送达,全程共用这一时限。排队时间计入其中,进度通知不会重置时限。 |
| 等待队列 | 每条隧道 1,000 个请求 | 所有 MCP 通道共享此限额。仅统计正在等待 tunnel-client 轮询获取的请求,已取出执行的请求不计入其中。 |
这些限制用于保护服务,不构成对吞吐量或延迟的保证。为清理而保留队列记录不会延长 120 秒的请求时限。如需提高隧道数量或流量上限,请联系 OpenAI 支持团队。
设置 tunnel-client
打开平台隧道设置,使用页面上的下载链接,或下载 tunnel-client 在 openai/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 工具都依赖正在运行的客户端。
在从 ChatGPT、Codex 或 API 流程进行测试之前,您可以在 /ui 的本地管理界面中查看正在运行的客户端是否健康、就绪并已连接。
选择 tunnel-client 的运行位置
请在能够访问私有 MCP 服务器的同一信任边界内运行 tunnel-client。常见部署方式如下:
- Kubernetes 边车容器: 在同一个 Pod 中同时运行
tunnel-client和 MCP 服务器,并通过localhost连接。 - 独立的 Kubernetes Deployment: 如果已经可以通过私有 Service 访问 MCP 服务器,可单独运行
tunnel-client。 - 虚拟机或 systemd 服务: 在能够通过私有网络访问 MCP 服务器的主机上运行
tunnel-client。
从 ChatGPT 连接
前往 ChatGPT 插件,选择加号按钮,然后选择添加自定义 MCP 服务器。选择隧道作为连接方式。从 ChatGPT 列表中选择可用的隧道,如果您已有有效的 tunnel_id,也可以直接粘贴。配置身份验证,阅读风险提示,选择我已了解并希望继续,然后选择创建为插件。
如果隧道未出现在 ChatGPT 中,请确认隧道除了关联平台组织,还关联了目标 ChatGPT 工作空间,并确认应用创建者具有隧道的读取和使用权限。
使用 Codex 设置并验证隧道
要让 Codex 引导您完成设置,请允许它通过浏览器访问平台和 ChatGPT,并通过终端访问能够连接到私有 MCP 服务器的主机。将以下提示词粘贴到 Codex 中:
请帮我设置一条私有的安全 MCP 隧道,将我的内部 MCP 服务器连接到 ChatGPT,并完成端到端验证。请通过浏览器或计算机界面操作,并使用终端执行命令。按照 https://developers.openai.com/api/docs/guides/secure-mcp-tunnels 和 https://github.com/openai/tunnel-client/blob/master/docs/onboarding.md 中的说明操作,逐步核对当前界面和 CLI 帮助。
先确定目标平台组织和 ChatGPT 工作空间、MCP 服务器的 HTTP URL 或 stdio 命令,以及运行客户端的主机。检查现有的隧道、密钥和 ChatGPT 自定义 MCP 插件,复用其中合适的资源。确认隧道关联了目标组织和工作空间,并核对权限。隧道创建者需要读取和管理隧道的权限(Tunnels Read + Manage),权限受限的运行时密钥和插件操作人员都需要读取和使用隧道的权限(Tunnels Read + Use)。
不要在聊天、命令参数、日志、截图或配置文件中包含密钥或其他凭据的明文值。请让我在本地通过安全的输入方式提供这些值,或通过环境变量引用它们。安装受支持的 tunnel-client,运行 `tunnel-client help quickstart`,配置服务器,然后运行 `tunnel-client doctor --profile <name> --explain`。启动客户端,确认它已就绪并且正在轮询。让客户端持续运行,以便发现和调用工具。
在 ChatGPT 插件中添加私有的自定义 MCP 服务器,或完成现有服务器的设置。将连接方式设为隧道(Connection: Tunnel),选择同一条隧道,配置所需的身份验证,然后执行一次安全且有代表性的工具调用。逐项报告验证结果,并说明实际观察到了什么。如果某一步受阻,请给出确切的错误信息和下一步操作。只有在 ChatGPT 成功调用工具后,才确认设置完成。
从 Responses API 连接
在 MCP 工具定义中,通过 tunnel_id 传入隧道标识符。请勿将 OpenAI 托管的隧道端点作为 server_url 传入。仅当 Responses API 可以直接访问 MCP 服务器时,才使用 server_url。
curl https://api.openai.com/v1/responses \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-d '{
"model": "gpt-6.2-astra",
"input": "Use the private MCP server to answer my request.",
"tools": [
{
"type": "mcp",
"server_label": "private_mcp",
"tunnel_id": "tunnel_0123456789abcdef0123456789abcdef"
}
]
}'安全与网络
私有 MCP 服务器始终位于客户控制的环境内。tunnel-client 使用运行时 API 密钥通过出站 HTTPS 连接访问 OpenAI,必要时还可启用控制平面 mTLS。
- MCP 服务器地址保持私有,仅在运行
tunnel-client的环境内使用。 tunnel-client向 OpenAI 隧道控制平面进行身份验证,支持此功能的 OpenAI 产品则使用 OpenAI 托管的隧道端点。- 隧道访问受现有组织和工作空间的访问控制约束,无需另设公网入口。
tunnel-client支持企业网络配置,包括出站代理、自定义 CA 证书包、控制平面客户端证书以及 MCP 端的mTLS。
日志记录范围
安全 MCP 隧道将隧道传输与产品的应用级日志记录分开处理:
- 隧道不会将控制平面身份验证、长轮询和响应流量或单次隧道传输请求记录为 ChatGPT 合规平台的应用事件。
- API 平台的审计日志以
tunnel.created、tunnel.updated和tunnel.deleted事件记录隧道元数据的变更。 - 当 ChatGPT 通过安全 MCP 隧道访问自定义应用时,隧道仅负责传输。应用仍按常规方式记录应用级合规日志,包括应用调用日志和应用身份验证生命周期日志,例如关联应用或解除关联时产生的
APP_AUTH_LOG。
高级用法:调用允许列表中的 HTTP 目标
安全 MCP 隧道还支持从兼容的智能体或 API 流程向客户网络发起范围严格受限的 HTTP 调用。tunnel-client 内置了名为 Harpoon 的 MCP 服务器。Harpoon 按标签提供已配置的 HTTP 目标,允许调用方通过隧道调用这些目标,并对请求和响应施加限制。
如果您需要访问少量私有 REST 端点,又不希望向公网开放这些端点,可以使用此功能。Harpoon 不提供通用代理功能:调用方不能任意选择主机,只能向客户配置的目标发送请求,并使用客户指定的方法。
故障排查
- 平台隧道设置提示“需要隧道访问权限”: 隧道权限在组织级别授予,而非项目级别。选择目标平台组织,然后请组织所有者或 RBAC 管理员为您分配相应角色或将您加入相应用户组。查看隧道需要读取权限,创建、编辑或删除隧道需要读取和管理权限。如果没有匹配的角色,管理员可以创建角色,将其分配给用户组,再将您加入该组。您还需要使用权限才能运行
tunnel-client或在连接器设置中选择隧道。新分配的角色最多可能需要 30 分钟才能生效。 - ChatGPT 中看不到隧道: 检查隧道是否除了关联平台组织,还关联了目标 ChatGPT 工作空间,然后检查连接器操作人员是否具有隧道的使用权限。如果系统无法为企业账号自动关联工作空间,请联系您的 OpenAI 客户团队,请其审核并手动指定关联关系。
- 连接器发现或工具调用失败: 确认
tunnel-client run ...仍在运行,然后重新运行tunnel-client doctor --profile <name> --explain。 - 可以查看隧道,但无法编辑: 操作人员可能只有隧道的读取权限,缺少隧道的管理权限。
tunnel-client提供/healthz、/readyz、/metrics端点,以及位于/ui的本地管理界面。- 默认情况下,管理界面仅允许通过回环地址访问。仅在确实需要从运维网络访问时才开放远程访问。
- 从 ChatGPT、Codex 或 API 流程进行测试之前,请通过这些端点和界面确认客户端运行正常、已就绪且正在轮询。
- 如果客户端未连接,通过隧道发送的请求将会失败,直到
tunnel-client重新连接。 - 原始 HTTP 日志记录默认关闭,为技术支持导出的数据会经过脱敏处理。
OAuth
- OAuth 发现请求可以通过隧道传输,因此 MCP 服务器本身可以保持私有。
- 隧道会保留浏览器端 OAuth 流程所需的上游授权服务器元数据。
- 授权服务器本身不会自动接入隧道。如果公网和运行
tunnel-client的主机都无法访问授权服务器,即使 MCP 服务器可达,OAuth 流程仍可能失败。
配置位置
- 在平台隧道设置中管理 OpenAI 托管的 MCP 隧道端点。
- 添加自定义 MCP 服务器时,可在 ChatGPT 插件中选择使用隧道。
- 对于 Codex 或 API 流程,请使用相应产品提供的、通过隧道连接的 MCP 目标。
后续步骤
- 在平台隧道设置中创建或管理隧道。
- 要验证
tunnel-client配置,请运行tunnel-client doctor --profile <profile> --explain。 - 从 ChatGPT 插件或您使用的其他兼容 OpenAI 产品连接隧道。
