chatgpt-mcp-connect

Reproducible recipes for connecting local and remote MCP servers to ChatGPT.

Your MCP server already works in Claude Code or Cursor. ChatGPT can't see it. This repo is the last mile — thirteen paths that were actually built, run, and verified end to end, written down so you don't spend an afternoon rediscovering them.

中文说明 · Architecture · Security · Troubleshooting

Why this exists

ChatGPT will not talk to your MCP server unless all four of these are true at once:

Nothing in the MCP ecosystem hands you those four. Every guide stops at "your server works locally", and the gap between that and a working ChatGPT connector is where the afternoon goes. The protocol is documented; the assembly is not.

So this is the assembly: which piece goes where, what breaks, and how to tell which layer broke.

Start here

git clone https://github.com/yoruuuchan/chatgpt-mcp-connect.git
cd chatgpt-mcp-connect

0. Decide whether you are exposing one MCP or a runtime. If you want one persistent ChatGPT connector in front of multiple Workspaces, Skills, or upstream MCP servers, start with recipes/mcpx. MCPX is the aggregation/runtime path; the rows below are the direct leaf-server paths.

1. Find your row. Answer two questions about the MCP server you want to connect directly:

If the upstream is already hosted on public HTTPS but only gives you a static Bearer/API token, do not tunnel it back through your workstation. Use recipes/mcdonalds as the reference shape: a Cloudflare Worker provides ChatGPT-compatible OAuth at the edge and swaps the OAuth bearer for the upstream token.

If the data source is a mobile device that must stay reachable while roaming or sleeping away from your workstation, use recipes/listening-bridge: the device keeps one outbound persistent WebSocket to a hosted MCP service, while ChatGPT reaches that hosted service through OAuth over public HTTPS.

2. Follow the closest recipe. Even if your MCP server isn't one of thirteen, one of them has your shape.

3. Check your work before touching ChatGPT.

node scripts/doctor.mjs --url https://mcp.example.com --upstream 127.0.0.1:8770 --gateway 127.0.0.1:8771

It probes each hop in order and names the first one that's broken, instead of leaving you to guess from a blank ChatGPT error.

[  ok  ] 1. MCP server            127.0.0.1:8770 accepting connections
[ FAIL ] 2. OAuth gateway         gateway is up and reports upstream unreachable (HTTP 503)
         The gateway itself is fine — what sits behind it is down.

For a server with built-in OAuth such as MCPX, omit --gateway and point --upstream at the server itself.

Recipes

Each was built and verified on real hardware. Each records what was tested, what wasn't, and when.

The variety is the point. Between them they cover four ways to do OAuth — from writing nothing at all to running your own gateway — and several public-exposure shapes: Cloudflare Tunnel, Worker custom domains, and Tailscale Funnel as an alternative when you do not have a Cloudflare-managed domain. MCPX adds a second architectural choice on top: connect ChatGPT directly to a leaf MCP, or put an MCP runtime in front of a changing set of local capabilities. Read docs/architecture.md to pick, or recipes/ for the full comparison.

What's in here

recipes/     thirteen verified end-to-end paths, including a runtime aggregation path
templates/   oauth-gateway/  — OAuth 2.1 in front of any HTTP MCP server
             supervisor/     — keep the processes alive across reboots
scripts/     doctor.mjs      — layered connectivity check, no dependencies
docs/        architecture · security · troubleshooting
SKILL.md     agent skill: point Claude Code or Codex at this repo

The two pieces people are usually missing are templates/oauth-gateway — about 230 lines of Node that turns a plain HTTP MCP server into one ChatGPT can authenticate against — and docs/troubleshooting.md, which is the list of real failures rather than a list of things that might go wrong. The one that cost the most to find: every auth failure returning HTTP 500 instead of 401, from two unrelated causes that produce an identical symptom.

Use it as an agent skill

The repo doubles as a skill for coding agents, so a fresh session starts from the architecture instead of re-researching whether ChatGPT supports MCP at all.

git clone https://github.com/yoruuuchan/chatgpt-mcp-connect.git ~/.claude/skills/chatgpt-mcp-connect   # Claude Code
git clone https://github.com/yoruuuchan/chatgpt-mcp-connect.git ~/.agents/skills/chatgpt-mcp-connect   # Codex

Then add one line to your global CLAUDE.md or AGENTS.md:

When a task involves connecting a custom MCP to ChatGPT, read and follow the chatgpt-mcp-connect skill first.

Scope

This gives you a working, authenticated, public MCP endpoint that survives a reboot, and a way to tell which layer is broken when it isn't working. It also documents when a single runtime connector is a better fit than exposing every leaf MCP independently.

This is not an MCP framework, a proxy to install, a hosted service, or a sandbox. It doesn't fork or wrap any upstream MCP server — every recipe points at the real project and tells you how to configure it. And it does not constrain what an authenticated caller can do; read docs/security.md before you expose anything, especially the part about turning off the tools you don't need.

The original workstation recipes were verified on 2026-08-18, Unreal on 2026-08-19, the hosted McDonald's edge-OAuth recipe and MCPX runtime on 2026-08-21, QQ Mail on an always-on Linux cloud host on 2026-09-05, and Listening Bridge's mobile outbound-WebSocket path on a vivo phone on 2026-09-11. DevSpace's public exposure layer moved from Tailscale Funnel to Cloudflare Tunnel on 2026-09-09; the Funnel path remains documented as a previously tested alternative. Each recipe states what was live-checked on that date and what wasn't — where an application wasn't running at verification time, the recipe says so rather than implying more coverage than it has.

Attribution

Every MCP server here belongs to someone else. This repo links to them; it copies nothing and forks nothing.

None of these projects endorse or maintain these recipes. Bugs in a recipe are this repo's problem; take upstream bugs upstream.

Contributing

A new recipe is welcome if you actually ran it. Follow the structure of an existing one, state your tested environment and date, and mark anything you couldn't verify as unverified rather than filling it in. Corrections to a recipe that has drifted are just as useful — these depend on upstream projects that move fast.

License

MIT — see LICENSE. Upstream projects keep their own licenses.