Guide

ChatGPT Secure MCP Tunnel: OpenAI tunnel setup, ID and errors

ChatGPT's Secure MCP Tunnel, often called the OpenAI tunnel, is an OpenAI feature that connects ChatGPT to a private or localhost MCP server without giving that server a public URL or opening inbound firewall ports. You run OpenAI's tunnel-client next to the server. It makes an outbound HTTPS connection to OpenAI, picks up the MCP requests ChatGPT sends, forwards them to your server and returns the responses.

This guide is based on OpenAI's own documentation. If you would rather not run the tunnel by hand for every project, a short comparison with TunnelGPT is near the end.

Where do I find and reuse an existing OpenAI Secure MCP Tunnel ID?

Open OpenAI Platform → Settings → Organization → Tunnels, select the organization that owns your existing tunnel and copy its complete tunnel_id. Reuse that exact tunnel ID in tunnel-client (--tunnel-id or CONTROL_PLANE_TUNNEL_ID) and in ChatGPT, under Connection: Tunnel. The ID identifies a tunnel; it is not an API key.

If ChatGPT does not show the tunnel, check that it is associated with the target ChatGPT workspace and that the account operating the connector has Tunnels Read + Use. An organization association alone does not make it available in every workspace.

Which API key permissions does tunnel-client need?

For runtime use, set CONTROL_PLANE_API_KEY to a Restricted API key with Tunnels Read + Use for the intended tunnel. OpenAI’s permissions guide distinguishes reading tunnel information from using the tunnel to handle requests.

Creating, editing or deleting tunnel records is administration and requires Tunnels Read + Manage. Keep administration credentials separate from the restricted key used by the running client. The key’s principal also needs access: choosing key scopes does not grant that account a missing role. ChatGPT workspace permission to add or use a custom MCP server is a separate check.

Why is my OpenAI Secure MCP Tunnel not connecting?

Identify the stage that failed before changing credentials or restarting processes. A Platform access error, a runtime authorization failure, a readiness problem, a workspace association issue and an unreachable local MCP server need different checks. OpenAI’s tunnel-client troubleshooting guide separates these cases.

Platform access. Confirm the selected organization and your Platform role. Reading tunnel information needs Read; creating or editing a tunnel needs Read + Manage.
Runtime authorization. Confirm the process uses the intended restricted CONTROL_PLANE_API_KEY, its principal has Tunnels Read + Use, and its tunnel ID matches ChatGPT. A 403 alone does not identify the cause: inspect the failing request and the credential it used. If reading metadata succeeds but polling fails with 401/403, check Use on the key’s principal and the runtime key scopes.
Process and readiness. Run tunnel-client doctor --profile <name> --explain as a local preflight. /healthz reports that the process is alive; /readyz reports startup readiness. Resolve the specific failing check rather than treating a live process as a working connector.
ChatGPT workspace. Check that the tunnel is associated with the workspace where you are adding the custom MCP server, that the operator has Read + Use, and that ChatGPT selects the same ID as the running client.
Local MCP server and network. Check the configured stdio command or MCP URL from the environment where tunnel-client runs. It needs outbound HTTPS to OpenAI and access to the MCP server; the local server does not need a public inbound port.

doctor checks local prerequisites; it does not prove an end-to-end MCP tool call from ChatGPT succeeded or that the key can poll the target tunnel. Neither /healthz nor /readyz proves that call on its own. Finish by requesting a harmless, read-only tool that your MCP server exposes in ChatGPT, and inspect the actual returned result.

Checked on 26 October 2026

Sources: OpenAI's Secure MCP Tunnel guide, the Add custom MCP server page and the openai/tunnel-client docs. The OpenAI pages carry no date stamps.
It works with ChatGPT, Codex and the Responses API, for private connections. It is not for publishing a public plugin.
Two permission systems apply: Tunnels permissions in your OpenAI Platform organization, and custom MCP server permissions in your ChatGPT workspace.
Default limits: 600 MCP requests per minute, 10 MiB per request or response and a 120-second deadline per request.

What you need before you start

A `tunnel_id` from Platform tunnel settings.
A restricted API key with Tunnels Read + Use, for tunnel-client.
An MCP server that tunnel-client can reach over stdio (a command it starts) or HTTP.
Platform roles. Creating or editing a tunnel needs Tunnels Read + Manage; running tunnel-client or selecting the tunnel in ChatGPT needs Read + Use. A Platform organization owner or RBAC administrator grants them.
ChatGPT access. Custom MCP servers are added in ChatGPT on the web, subject to workspace permissions and security restrictions, including Lockdown. In a shared workspace, ask its admin.
Outbound HTTPS to api.openai.com:443. No inbound access is needed.

OpenAI's developer guides do not list which ChatGPT plans can add custom MCP servers. Check OpenAI's Help Center article on developer mode and MCP apps in ChatGPT for your plan.

How to set up a Secure MCP Tunnel, step by step

Create the tunnel and copy its ID. In Platform tunnel settings, create a tunnel and associate it with the ChatGPT workspace where you will add the server, not only with a Platform organization. Copy the tunnel_id. Allow 25–30 seconds before expecting it to be ready.
Create a restricted key with Tunnels Read + Use. In Platform API keys, create a Restricted key and select Tunnels Read + Use. Do not use an All key or an admin key for the long-running client.
Run tunnel-client next to the MCP server. Download it from Platform tunnel settings or the latest release. On macOS, install it with Homebrew, brew install openai/tools/tunnel-client, because directly downloaded ZIPs are not notarized. Create a profile, check it with doctor, start it with run and keep it running.
Add it in ChatGPT. Go to ChatGPT Plugins, select the plus button, then Add custom MCP server. Enter a name, choose Tunnel under Connection, and select your tunnel or paste the tunnel_id. Configure authentication, select I understand and want to continue, then Create as a plugin.
Install the plugin and use it. In a new conversation, type @ and select it. Write actions ask for your confirmation by default.

The commands from OpenAI's guide, for a local stdio server:

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

For an HTTP MCP server, use --mcp-server-url instead of --mcp-command. tunnel-client help quickstart prints the shortest path for your setup.

What is the tunnel ID?

The tunnel ID names one OpenAI-hosted tunnel endpoint. It is tunnel_ followed by 32 lowercase letters or digits, for example tunnel_0123456789abcdef0123456789abcdef, and some IDs add a four-character namespace: tunnel_<namespace>_<32 characters>. Copy it exactly as Platform shows it. The same ID goes into tunnel-client (--tunnel-id or CONTROL_PLANE_TUNNEL_ID) and into ChatGPT.

What is tunnel-client?

tunnel-client is the program OpenAI publishes for Secure MCP Tunnel. It runs beside your MCP server, long-polls OpenAI for queued MCP requests, forwards each JSON-RPC request to the server and posts the response back. It reads the key from CONTROL_PLANE_API_KEY and serves /healthz, /readyz, /metrics and a local admin UI at /ui, by default on 127.0.0.1:8080.

With a stdio server, run only one tunnel-client per tunnel ID, even during a restart. Give each independent server its own tunnel ID.

Data flow and security: what goes to OpenAI and what stays local

Stays on your side: the MCP server and its address. It needs no public listener and is reached only from where tunnel-client runs.
Goes through OpenAI: every MCP request ChatGPT sends and every response your server returns. The tool results ChatGPT uses are sent to OpenAI so it can answer. The tunnel keeps the server private; it does not make the conversation local.
Direction: outbound HTTPS only, to api.openai.com:443 on /v1/tunnel/*.
Logging: raw HTTP logging is off by default and support exports are redacted. Tunnel changes appear in Platform audit logs.
OAuth: discovery can pass through the tunnel, but the authorization server itself is not tunneled, so it must be reachable.
Trust: OpenAI says to connect only MCP servers you trust. Tools without the readOnlyHint annotation are treated as write actions.

Common problems and fixes

"Unsafe URL" with a localhost address. ChatGPT does not accept localhost or private addresses as a Server URL. Choose Tunnel under Connection instead.

"Tunnels access required" in Platform. Tunnel permissions are organization-level, not project-level. Select the right organization and ask an owner or RBAC admin for Read, or Read + Manage to create tunnels. New roles can take up to 30 minutes to apply.

The tunnel does not appear in ChatGPT. Check that it is associated with the ChatGPT workspace, not only a Platform organization, and that you have Tunnels Read + Use. A tunnel tied only to a personal Platform organization does not automatically appear in an Enterprise or Edu workspace.

Tunnel not ready, or tools are not discovered. tunnel-client must be running while you create the plugin and on every call. Check /readyz, not only /healthz, confirm ChatGPT uses the same tunnel ID, and run tunnel-client doctor --profile <name> --explain.

Key scope errors (401/403). Check which request and credential failed. If metadata reads succeed but runtime polling fails, check Tunnels Use for the key’s principal and Read + Use on the restricted runtime key. A failure while creating or editing tunnels is an administration check: confirm Read + Manage. A 403 by itself does not distinguish these stages.

It worked, then stopped. If the computer running tunnel-client sleeps, goes offline or the process exits, requests fail until it reconnects. Keep the machine awake and the client running.

Doing it yourself vs letting TunnelGPT run it

Running the tunnel yourself needs only OpenAI's tools and gives you full control, but each project or MCP server needs its own tunnel, client process and ChatGPT plugin. TunnelGPT is an independent Mac app, not affiliated with OpenAI, that runs that part for you.

Secure MCP Tunnel by hand vs TunnelGPT, checked 25 October 2026
	Secure MCP Tunnel yourself	TunnelGPT
Tunnel and key	You create them in Platform.	You still create them. TunnelGPT does not create the OpenAI tunnel or credential for you; the guided setup walks you through it.
tunnel-client	You install, run and restart it for each server.	Runs it for you, pinned and hash-checked: one connection per project and one per local MCP.
Access	Whatever your MCP server exposes.	Read-only first; editing is a separate switch per project.
Commands	Up to your MCP server.	Need a separate grant and run in an offline Docker container.
Platform	Anywhere tunnel-client runs.	Signed Mac app, Apple Silicon (M1 or later) only. Needs Docker 24+.
Cost	OpenAI's guide states no separate tunnel price.	$9.97 USD one-time, Version 1 Perpetual License, with a 3-day free trial.

Both use the same OpenAI Secure MCP Tunnel, with no TunnelGPT relay server in the data path, and your ChatGPT plan and OpenAI's limits apply either way. See also TunnelGPT vs DIY MCP tunnels.

Frequently asked questions

Is Secure MCP Tunnel free?

OpenAI's guide does not state a separate price for tunnels. Check OpenAI's documentation and your plan for current terms.

Does it work on ChatGPT Plus, Pro or Business?

OpenAI's developer guides say custom MCP servers depend on account and workspace policies, but do not list plans; check OpenAI's Help Center for yours. Our team tested TunnelGPT, which uses this tunnel, on ChatGPT Plus and Pro in October 2026. That does not cover every account, and availability can change.

Can I use it with Claude or other MCP clients?

OpenAI documents Secure MCP Tunnel only for its own products: ChatGPT, Codex, the Responses API and AgentKit. For other clients, check their documentation.

Do I need a VPS?

No. The MCP server can stay on your laptop or a private network, because tunnel-client only needs outbound HTTPS. That machine must stay on and connected while ChatGPT uses it. See how to use local MCP servers with ChatGPT.

Sources

Next steps

Product