ModelBridge

An MCP server that gives a ChatGPT connector (or any other MCP client) a working sub-agent — and, optionally, one that reads files, runs commands, and works a multi-step task to completion on your machine.

It ships pointed at DeepSeek, which is the cheap default rather than the point. The design is model-agnostic: the sub-agent's brain is whatever Anthropic-compatible endpoint you put in DEEPSEEK_BASE_URL, and the harness around it is a swappable part. That is where the name comes from.

中文说明 · Changelog · Contributing · Security

What this is actually for

It puts another working sub-agent inside your ChatGPT conversation — one whose brain can be any model you like.

Be precise about this, because the project gets retold wrong a lot: ChatGPT's own sub-agents (Luna and friends) can already do real work — they read and write files on your machine, run commands, and iterate. This bridge is not filling in a missing capability.

The real constraint sits elsewhere: sub-agent slots only accept OpenAI's own model tiers (Sol / Terra / Luna). An external model cannot be registered as one. So the moment you want a different model doing that work — faster, cheaper, or independent enough to review the implementer — the only door in is an MCP connector.

And an MCP tool is a text interface by default: you call it, you get text back. To let an external model actually work, you have to hand it a whole environment first.

The mechanism matters more than the outcome: it does not plug DeepSeek in, it gives DeepSeek hands. A bridge that only forwards an API hands the host one more model to ask. This one does not — on an agent job it spawns a full agent harness (Claude Code) as a child process, pointed at DeepSeek's Anthropic-compatible endpoint. So the loop, context compaction, prompt caching and tool implementations — everything that makes a model able to work — are an existing, maintained implementation rather than a hand-rolled imitation. What the host gets is therefore a sub-agent that can do the job, not a Q&A endpoint.

And it is exposed as one MCP tool, so any MCP-capable host can call it; the ChatGPT connector is one door in, and so far the only one tested. The harness layer is a swappable part — Claude Code is its current implementation, not the essence of the design.

About "faster" — an honest note. From my own use the felt difference is two things: fewer steps for the same task, and a higher chance of getting it right the first time. But I have not benchmarked it — I have not run the same task set against Luna and DeepSeek as a controlled comparison. So that is a subjective impression, not performance data. It may also not hold for every task: there is community feedback that non-OpenAI models do worse on apply_patch-style mechanical edits. Try it on a small slice first; do not switch wholesale.

Measured, not intended: given "read witness.txt, reverse its contents, write them to answer.txt", the sub-agent ran 3 steps over 2 min 25 s; the answer.txt on disk matched the expected string byte for byte, next to a nonce that only a real result can produce. A chat transcript agreeing with itself is not evidence — bytes on disk are.

That measurement shows it really does the work. It does not show it is faster than Luna — the efficiency difference is still an impression, not a comparison.

⚠️ This capability is off by default. With no DEEPSEEK_ALLOWED_ROOTS set, the bridge can only spend your DeepSeek quota and cannot touch your computer. Turn it on and anyone holding the URL can read and write files and run commands on your machine — "can run commands" means "has your computer." Read the security model first.

Related MCP server: deepseek-mcp

Why this exists

ChatGPT's sub-agent slots only accept OpenAI's own model tiers (Sol / Terra / Luna). You cannot register an external model as a sub-agent. The only supported entry point for a foreign model is an MCP connector — i.e. wrapping it as a tool that the main agent can call.

That has real consequences you should understand before deploying:

The main practical payoff is cross-vendor independent review. If your prompt requires that a reviewer must not reuse the implementer's conclusions, a model from a different vendor satisfies that requirement far better than another tier of the same stack — there is no shared training lineage to echo.

Swapping the host model does not break this. The bridge does not depend on Sol, or on which tier you are running. It depends on one thing: sub-agent slots are not open to external models. That is a property of the platform, not of the model tier — change tiers and the slot is still closed, so this bridge is still the only way in. Only the sub-agent side is ever re-pointed: edit DEEPSEEK_BASE_URL and DEEPSEEK_MODEL in .env and run npm run ctl -- reload (the tunnel is left alone, so the URL does not change). The one change that would make this redundant is platform-level, not model-level: OpenAI opening the sub-agent slot to external models.

The bridge itself is a standalone Node process that talks only to api.deepseek.com. Agent jobs are the exception: to run one it spawns Claude Code as a child process, pointed at DeepSeek's Anthropic-compatible endpoint. The bridge never runs inside a host — it launches one.

Architecture

ChatGPT (Sol) ──HTTPS──▶ Cloudflare edge ──tunnel──▶ bridge (127.0.0.1:8787)
                                                            │
   deepseek_flash(task, mode, files) ───────────────────────┤──▶ api.deepseek.com ──▶ text back
                                                            │
   deepseek_agent_start(task, workspace) ──▶ job registry ──┤   abort · TTL · nonce · step/time ceilings
   deepseek_agent_poll(job_id) ◀────────────  snapshots     │
                                                            │
                                            harness: claude -p ──▶ api.deepseek.com/anthropic
                                                 │  Read / Write / Edit / Bash
                                                 │
                                                 └─ approval prompt (stdio MCP child of the harness,
                                                    never reachable over the URL) ──▶ you, via `npm run ctl`

Once a tool call reaches that approval prompt it is routed one of three ways, and the split is the point:

--add-dir is not what enforces the middle row. It only adds an accessible directory; it restricts nothing. The boundary comes from listing the file tools in the harness's permissions.ask, which is the only knob that makes --permission-prompt-tool fire in headless mode — measured, not assumed. Before that, a job whose workspace was D:\project could Read C:\Users\you\.env with no prompt at all.

• Transport: MCP Streamable HTTP, stateless (sessionIdGenerator: undefined, a fresh server + transport per request so callers never share state). The job registry is deliberately not per-request — it is created once per process, or every job would be forgotten the moment its start call returned.

• Responses stream as SSE rather than buffered JSON. This keeps bytes moving on the wire, which avoids Cloudflare's free-tier 524 timeout on long DeepSeek calls.

• Auth: a capability URL. The MCP endpoint is /mcp/<64-hex-secret>; the path is the credential. The bare /mcp path and any wrong path return 404, indistinguishable from nothing being there — because ChatGPT's connector form has no Bearer-token field.

• Agent jobs are asynchronous by necessity. ChatGPT's tool-call budget is around 60 s; a real task is not. agent_start blocks up to 45 s for a fast job and otherwise returns a job id to poll.

Requirements

• Node.js >= 24 (uses native TypeScript type-stripping; no build step)

• A DeepSeek API key — create one at https://platform.deepseek.com

• cloudflared for the quick tunnel (or bring your own deployment — see below)

• For agent jobs only: Claude Code on PATH (or set BRIDGE_CLAUDE_BIN). The one-shot deepseek_flash tool has no extra dependencies, and the offline test suite does not need either this or an API key.

Quick start

Two ways in. The wizard asks the questions and writes .env for you, then brings everything up; do it by hand if you would rather see every value before it is written.

The guided way

git clone https://github.com/CassiaTw1g/modelbridge.git
cd modelbridge
npm run setup

It runs on a bare clone — no npm install, no .env — because it is the thing that creates both. Have your API key ready to paste.

On Windows you can also double-click windows/0-首次安装.bat, which is the same thing.

It asks five things:

Every answer is written to .env as it is given, so Ctrl+C leaves a usable file and rerunning carries on from where you stopped. It ends by starting the server, opening the tunnel, copying the connector URL to your clipboard and printing it.

Language is picked up from the OS locale; override with npm run setup -- --lang zh or --lang en (also BRIDGE_LANG).

Then go to Register the connector. To check everything afterwards, see Verification.

The manual way

git clone https://github.com/CassiaTw1g/modelbridge.git
cd modelbridge
npm install
cp .env.example .env

Edit .env:

1. Set DEEPSEEK_API_KEY to your key. Use a dedicated key for this bridge so it can be revoked independently, and set a spend cap on it in the DeepSeek console as a last line of defence.

2. Generate the path secret:

   npm run ctl -- secret

   This writes MCP_PATH_SECRET=<random hex> into .env (or prints it if .env doesn't exist yet).

Start the server and open the tunnel:

npm run start     # background server on 127.0.0.1:8787
npm run tunnel    # cloudflared quick tunnel; prints the public URL and the full MCP endpoint

npm run tunnel prints the exact URL to paste into ChatGPT:

公网端点 : https://<random>.trycloudflare.com/mcp/<your-secret>

It checks first that the local port is actually answering before it opens anything — a live PID is not the same as a live service, and a tunnel in front of a dead port produces a URL that fails in a way that looks like ChatGPT's fault.

Register the connector

1. Open ChatGPT on the web (connectors cannot be configured from desktop or mobile).

2. Settings → Plugins → MCP → Add server (alternatively: Settings → Connectors → Advanced → Developer mode).

3. Type: Streamable HTTP. Authentication: No authentication.

4. URL: the full https://<random>.trycloudflare.com/mcp/<your-secret> — including the /mcp/<secret> path. Pasting only the domain will not work.

5. Save. The connector handshake shows up in the log as server/discover → initialize → notifications/initialized → tools/list.

Tell your main agent when to use it

The tool description is the router. It states dispatch conditions, not just what the tool does — this is what prevents the calling agent from picking it arbitrarily. Add a rule to your system prompt that is mutually exclusive with your sub-agent rules, e.g.:

Tasks needing cross-vendor independent review (security review, counterexample construction) → call the deepseek_flash tool, do not delegate to a sub-agent. Tasks needing file access, parallelism, or same-stack collaboration → delegate to a sub-agent.

Tool reference

Three tools in two groups. All three are always registered — but until DEEPSEEK_ALLOWED_ROOTS is set, the two agent tools reject every workspace with an explanatory error, so the bridge stays read-only.

deepseek_flash — one question, one answer

Each mode gets a distinct system prompt. review explicitly instructs the model to treat any author conclusion in the material as an unverified claim and to state disagreements explicitly — that is the point of routing to an external vendor.

deepseek_agent_start — hand over a task that needs hands

Blocks up to 45 s (ChatGPT caps a tool call near 60 s). A fast job returns its result inline; anything longer returns a job_id.

The client hanging up does not cancel the job. The abort controller belongs to the job registry, not to the HTTP request — otherwise every caller that lost patience would silently kill the work it had just dispatched. Use npm run ctl -- job kill <id> to actually stop one.

deepseek_agent_poll — collect it

Every terminal payload carries a nonce minted at job creation. An agent that reports an outcome without quoting it does not have a result — that is the point.

Behind the job: what the sub-agent actually runs

A job spawns Claude Code (claude -p … --output-format stream-json) with ANTHROPIC_BASE_URL pointed at api.deepseek.com/anthropic, so the model driving the loop is DeepSeek while the loop, context compaction, prompt caching and tool implementations are Claude Code's own. Every tool event is captured into the job trace, readable with npm run ctl -- jobs <id> --trace.

Configuration

All via .env (gitignored):

Agent jobs

With DEEPSEEK_ALLOWED_ROOTS unset, the agent tools reject every workspace and the bridge stays read-only. These settings only matter once you set it — read Security model first.

Lifecycle commands

npm run setup      # the first-run wizard (see Quick start)
npm run start      # background start (no-op if already running)
npm run stop       # stop server and tunnel
npm run restart    # restart server (stops the tunnel too — re-run `npm run tunnel`)
npm run status     # enabled state, PIDs, local + public endpoints
npm run logs       # last 40 log lines
npm run url        # copy the full connector URL to the clipboard, and print it
npm run tunnel     # start the Cloudflare tunnel, print the public URL
npm run untunnel   # stop the tunnel only
npm run auto       # show the current approval mode
npm run auto:on    # bypass approvals entirely (see Security model)
npm run auto:off   # back to "needs approval"
npm run enable     # clear the disabled flag
npm run disable    # stop everything and set the disabled flag
npm run uninstall  # stop and clear local state (leaves the project directory)

npm run start --foreground runs in the foreground for debugging.

npm run setup is rerunnable: it re-asks everything and rewrites the answers, and its workspace-roots answer is added to the list rather than replacing it, so a rerun cannot silently erase roots you added with npm run ctl -- allow.

npm run url is the one to reach for when rebuilding the ChatGPT connector: it prints https://<host>/mcp/<secret> and puts the same string on your clipboard, so you never have to hand-select the secret out of npm run status --show.

Rotating the path secret

npm run ctl -- rotate

Generates a new secret, restarts the server only, and prints the new public URL — which it also copies to your clipboard. The tunnel is deliberately left running: it forwards a port and has no idea what the path is, so the public hostname stays the same and only the last segment of the URL changes. (npm run restart would kill the tunnel too, costing you a new hostname and a second trip to the connector.)

Rotate whenever the URL may have been seen by anyone else. It is the only thing standing between your machine and whoever holds it.

On Windows, windows/7-轮换密钥.bat does the same thing from a double-click. If you prefer to drive it yourself, npm run ctl -- secret writes the secret without restarting anything — you then have to restart and update the connector by hand.

The same shape applies to the workspace allow-list: windows/8-添加项目目录.bat asks for a path and runs npm run ctl -- allow "<dir>", which writes .env and reloads with the tunnel left alone. Quote the path or use forward slashes — a bare D:\codex\3 typed into a POSIX shell loses its backslashes.

The secret is no longer printed

npm run ctl -- status / start / tunnel / secret now render the endpoint's secret as <密钥已隐藏>. Add --show to print it in full. Every printed copy outlives the moment — terminal scrollback, a shell transcript, a log pasted into a bug report — and the one real leak this project has had came from ctl printing it, not from anyone finding it. rotate still puts the full URL on the clipboard: a clipboard is not a log.

After editing code or .env

npm run ctl -- reload

Restarts the server alone. The tunnel is untouched, so the public URL is identical and the ChatGPT connector needs no attention. restart also stops the tunnel — a different command for a different situation.

Why you have to recreate the connector, and how to stop doing that

This is not you failing to find the button. ChatGPT's connector form may have no "edit URL" action at all — the documented recovery is to remove the connector and add it again. (Interfaces differ by account and by release, so it costs nothing to look for an edit control first.) And the bridge's default transport is a Cloudflare quick tunnel, which is handed a new random hostname on every start — so any tunnel restart changes the URL and costs you a rebuild.

Three ways out:

Start with the first row. Move on only if an occasional rebuild still bothers you.

A fixed hostname on your own domain

The quick tunnel is the default because it needs no setup. If you have a domain whose NS already points at Cloudflare, you can have a URL that survives restarts, reboots and restart alike — so the connector is built once and never touched again.

Two of the three steps happen in Cloudflare's dashboard and only you can do them. Create the tunnel at Networking → Tunnels → Create a tunnel (older guides say Zero Trust → Networks → Connectors; that menu redirects to the same page), then add the route under that tunnel's Routes tab:

Networking → Tunnels → your tunnel → Routes → Add route
  → Published application
  Subdomain    : mcp
  Domain       : your domain
  Service type : HTTP
  Service URL  : http://localhost:8787

Cloudflare creates the DNS record and the certificate for you — do not add one by hand. Then copy the long token the page shows you and come back here:

npm run ctl -- tunnel named mcp.example.com

It asks for the tunnel token (paste it — do not retype it into a file by hand) and writes your .env for you. On Windows, windows/11-固定域名.bat is the same thing from a double-click: it prints the dashboard steps, asks for the hostname and the token, and offers to switch the tunnel over once you confirm the route is saved.

⚠️ Skipping the route step is the trap. The tunnel will report connected to the edge, everything local looks healthy, and the domain returns 404 — because the "hostname → local port" route lives in Cloudflare's cloud, not on this machine. npm run ctl -- tunnel check lists what you have not done yet, and reports "registered with the edge" and "the domain actually answers" separately, because they are different facts. Nothing on your machine has to change to fix it: add the route and it starts working.

Nothing real is hardcoded here: the code and docs carry no one's domain, and every value comes from your own .env. TUNNEL_TOKEN is a credential on the same footing as the path secret — it is never printed, and ctl masks it.

Do not use the free ngrok tier. It injects a browser-warning page that needs an ngrok-skip-browser-warning request header to get past, and a ChatGPT connector cannot set custom headers — the connection is cut.

Agent job and approval commands

These read the files the server writes, so they work from a second terminal — and they still work if the server was restarted between the request and your answer.

npm run ctl -- jobs                # every job: state, steps, duration, nonce
npm run ctl -- jobs <id> --trace   # full trace: which tool at which step
npm run ctl -- job kill <id>       # cancel a running job, process tree included
npm run ctl -- pending             # commands waiting for your approval, in full
npm run ctl -- approve <id>        # let it run
npm run ctl -- deny <id>           # refuse it — the model is told why, and told not to route around it
npm run ctl -- audit               # recent approval decisions (--all for everything)

Verification

Four layers, cheapest first.

1. Offline suites — no network, no key, no money:

npm test

2. Public endpoint smoke test — exercises the real HTTP path:

npm run smoke                          # reads the tunnel URL from .state/tunnel.log
npm run smoke -- https://host/mcp/xxx  # or pass an endpoint explicitly

This asserts the health check, that a bare /mcp returns 404, that a wrong secret returns 404, and that a real tools/call returns non-empty content. It uses Node's fetch, not curl — see the Windows note below.

3. Acceptance — is the sub-agent actually capable? (online, costs a little)

npm run accept           # all three tasks
npm run accept -- --only B

Three tasks a chat-only model cannot pass:

Test B is the load-bearing one. Approval is deliberately disabled for the suite, which is why it is not part of npm test.

4. Did ChatGPT actually call us?

Server access logs and the chat transcript look identical whether the model truly called the tool or merely narrated doing so. The only trustworthy signals are:

• the log line tools/call deepseek_flash in npm run logs, and

• a matching entry in the DeepSeek console usage page.

For agent jobs, npm run ctl -- jobs must also show a record with more than one step and a real workspace path. If the chat shows a plausible answer but every one of those is silent, the calling model role-played the call. Re-sharpen the tool description or your dispatch rule.

Deployment options

The quick tunnel is fine to start, but its URL changes on every restart (you must re-edit the connector). For anything long-lived:

Avoid the ngrok free tier: its interstitial warning page requires an ngrok-skip-browser-warning header, which ChatGPT connectors cannot send, so the connection is severed.

Troubleshooting

Security model

Read this before exposing anything. It has two tiers, and they defend completely different things.

Tier 1 — protecting your bill

Applies always.

• The path secret is the credential. Anyone with the URL can spend your DeepSeek quota. Treat it like a password; rotate with npm run ctl -- secret.

• The secret is never written down by the bridge itself. The startup line, ctl logs, ctl audit and ctl jobs all render it as <密钥已隐藏>, and smoke masks it too. The reason is unglamorous: the only real leak this project has had came from the bridge's own log file, not from anyone guessing it. Every printed copy outlives the moment — scrollback, a transcript, a log pasted into a bug report.

• Bind to loopback. HOST defaults to 127.0.0.1. Do not set 0.0.0.0.

• Rate limiting is on by default and caps abuse if the URL leaks. It is a global bucket of tools/call requests rather than a per-IP window — see the variable table for why the per-IP framing was worse than useless here.

• A DeepSeek spend cap in the provider console is the final backstop — set it.

• Use a separate API key. Do not reuse a key that other tools depend on; a leaked bridge key should be revocable without collateral damage.

Tier 2 — protecting your computer

None of tier 1 stops this. Set DEEPSEEK_ALLOWED_ROOTS and whoever holds that URL can make the sub-agent read and write files on your machine, and run commands on it. "Can run commands" means "has your computer."

Out of the box the bridge is still read-only — the agent tools refuse every workspace and can only spend quota. The tiers are orders of magnitude apart:

The guardrails, and — just as importantly — what they are not:

• Fail closed. No DEEPSEEK_ALLOWED_ROOTS means every workspace is denied, never "anywhere by default".

• Every workspace goes through src/sandbox.ts, which is the only place a caller-supplied string becomes a real path.

• File tools are held to the workspace by src/harness/file-guard.ts, which reuses that same sandbox.admit(), so junctions, 8.3 short names, UNC paths, alternate data streams and trailing dots are one implementation with one regression suite (npm run test:guard) rather than a second, weaker copy. Measured before and after: a job whose workspace was D:\project used to read a file thousands of directories outside it in two steps with no prompt and copy the contents back into the workspace; it now stops at waiting_approval and the content never enters the run. In-workspace reads and writes still run unattended, so nothing was made slower for the normal case.

• Commands outside the allow-list pause the job for a human. Unanswered means deny; there is no default-allow path, and the approval channel is a stdio child of the harness rather than an endpoint on the URL — otherwise a caller could approve its own commands.

• Network tools always go to a human. WebFetch and WebSearch cannot be pre-approved and are not covered by the workspace at all — the workspace governs what comes in, and nothing in the original design governed what goes out.

• The sub-agent's environment is scrubbed of your credentials. claude-code.ts deletes every inherited variable whose name looks like a secret (API_KEY, _KEY, SECRET, TOKEN, PASSWORD, CREDENTIAL…) before spawning the harness, so a pre-approved node -e "console.log(process.env.X)" no longer reaches the bridge's own key, or an unrelated tool's. One variable is deliberately kept: ANTHROPIC_AUTH_TOKEN, which is the DeepSeek key the harness needs in order to call a model at all. Treat that key as readable-by-the-sub-agent — dedicated, revocable, spend-capped — because it is.

• Step, time and process-tree ceilings. A job that hits one settles as error and is given no nonce, so it cannot be mistaken for a finished review — but what it had already read comes back as a partial result. A brake should not also throw away the work that was done. Plus an audit log at .state/audit.log.

• Clear DEEPSEEK_ALLOWED_ROOTS and restart to go back to tier 1. That is a supported configuration and the recommended place to start: run read-only for a while, confirm the URL has not leaked, and only then consider turning it on.

This is not a security boundary. It is an observation window. The only real boundary is a sandbox or a VM — be at the machine while jobs run. Do not ship a public deployment of this with agent capabilities enabled.

Temporarily disabling approvals altogether (npm run auto:on)

While you are watching a batch of jobs run, approving commands one at a time is tedious. This switch turns the approval queue off wholesale:

npm run auto        # which mode am I in
npm run auto:on     # fully unattended
npm run auto:off    # back to "needs approval"

It removes more than you probably expect. It is not "commands stop asking" — the approval-mcp.ts child process is never spawned, so everything hanging off it goes away together:

What still applies: DEEPSEEK_ALLOWED_ROOTS still decides which directories may be opened as a workspace. The bypass loosens what happens inside one, not which ones can be opened.

A restart revokes it. The switch is a flag file at .state/auto-approve (not a .env key), and every service start deletes it. So reload / restart / rebooting all land back on "needs approval". That is on purpose: the bypass means "I am watching this job right now", not "I have stopped caring". reload, rotate and allow all restart the service and therefore revoke it too — each of them says so before it does.

Turning it on needs no restart — it takes effect on the next job (the check is re-read per job).

BRIDGE_CC_APPROVAL=off in .env is the other path and does not reset on restart. It is kept for npm run accept. If both are on, auto off only clears the flag file, and ctl status tells you plainly that the .env one is still live.

An honest note on auditing: under the bypass there are no approval_requested / approval_auto lines any more — the process that writes them never starts. What remains is the mode-change lines (auto_approve_on / auto_approve_off / auto_approve_cleared) and the harness's own tool-call trace in .state/jobs/<id>.json (one entry per call, capped at 400, readable with npm run ctl -- jobs <id> --trace). A record is not a gate — that is for looking back afterwards, not for stopping anything.

To report a vulnerability, see SECURITY.md.

License

MIT