deepseek-mcp-bridge

An MCP server that exposes DeepSeek as a tool for ChatGPT connectors (and any other MCP client) — and, optionally, as a sub-agent that reads files, runs commands, and works a multi-step task to completion on your machine.

中文说明 · 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

git clone https://github.com/CassiaTw1g/deepseek-mcp-bridge.git
cd deepseek-mcp-bridge
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>

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 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 tunnel     # start the Cloudflare tunnel, print the public URL
npm run untunnel   # stop the tunnel only
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.

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 to Tailscale Funnel only if an occasional rebuild still bothers you.

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.

To report a vulnerability, see SECURITY.md.

License

MIT