- Home
- Plugins
- Tools & Capabilities
- dsh-mcp-bridge
dsh-mcp-bridge
google-q-dot/dsh-mcp-bridge
MCP bridge for the running DeepSeek Harness desktop: 26 tools over a loopback MCP endpoint let Antigravity, Claude Code, Codex or Cursor drive the same live sessions, answer approvals and questions from the MCP side, keep per-session interaction modes, and use a reconnecting stdio proxy with a no-duplicate replay policy.
Install
dsh plugin --profile web add github:google-q-dot/dsh-mcp-bridgeREADME
MCP bridge for DeepSeek Harness
This is a Host plugin for the DeepSeek Harness (DSH) Desktop app, tested against 0.2.2-rc.3. It is not a standalone server: it must be installed into a DSH profile, and it only exists while the desktop Host process has the plugin row active. Once active it opens a loopback-only MCP endpoint inside the Host process and publishes its address and token in ~/.dsh/mcp-bridge.json, so a local MCP client — Antigravity, Claude Code, Codex, Cursor, or anything else that speaks Streamable HTTP or launches a stdio command — can drive the sessions the desktop window is showing. bin/dsh-mcp-stdio.mjs is the stdio proxy for clients that cannot dial HTTP themselves.
What it gives you
- A Streamable HTTP MCP endpoint at
http://127.0.0.1:<port>/mcp, authenticated with a bearer token. It speaks JSON-RPC 2.0 (initialize,ping,tools/*,resources/*,prompts/list,logging/setLevel) and answers tool calls with the MCP tools result envelope. - A stdio proxy (
bin/) that a client launches as itscommand, speaks newline-delimited JSON-RPC on stdin/stdout, and forwards everything to the loopback endpoint. - Shared sessions. The external agent works inside the real session log: its prompt, its model switch, its mode switch, the subagents it prompts and the results it reads are the same records and the same GUI state the desktop window is showing. Nothing is mirrored into a second, private transcript, and no custom session-log event types are written.
Install
The package is prepared for npm as dsh-mcp-bridge-server — the name dsh-market and Plugins → Add plugin will use once the first release is published.
From npm / dsh-market
- In the app: Plugins → Add plugin, search
dsh-mcp-bridge-server, install it, then confirm thedsh-mcp-bridgerow is present and enabled. - CLI:
dsh plugin --profile <profile> add dsh-mcp-bridge-server, then restart the app (or thedsh webprocess) when the host asks for it. - dsh-market: the market card installs the same npm package; no separate download step.
From this checkout (development)
This checkout is also installable directly as a local directory bundle:
- Install the directory through Plugins → Add plugin, or through the
plugin_managertool withinstall_bundleand the absolute path of this checkout as the target. - Confirm the plugin row
dsh-mcp-bridge(@local/dsh-mcp-bridgein this checkout) is present and enabled.
The bundle patch (cordis.patch.yml) inserts that single row. Activation opens the endpoint inside the Host process and writes the discovery file; there is no separate process to start and no pnpm install to run — the package has zero runtime dependencies.
Reloading after a source change
The desktop profile's HMR watches no module roots (@deepseek-ai/dsh-hmr is mounted with config.root: []), and the bundle is installed as a link: inside the profile's node_modules, so editing files in this repository does not hot-reload the Host plugin. Toggle the plugin row off and on in Plugins (or plugin_manager set_plugin on entry id include:dsh-mcp-bridge with enabled: false, then enabled: true), or restart the app: a fresh module generation loads, the listener rebinds to the same port, and the discovery file keeps its token — only instanceId (and startedAt) change.
Connect a client
Option A — stdio proxy (recommended for Antigravity, Claude Code, Codex, Cursor)
Point the client at the proxy script:
{ "mcpServers": { "deepseek-harness": { "command": "node", "args": ["<profile>/node_modules/dsh-mcp-bridge-server/bin/dsh-mcp-stdio.mjs"] } } }
<profile> is the DSH profile directory that has the plugin installed (the desktop app's profile is ~/.dsh/profiles/desktop). With the package installed globally or in the current project, npx --package dsh-mcp-bridge-server dsh-mcp-stdio runs the same proxy.
The proxy resolves the endpoint from the discovery file, so the client configuration does not change when the app restarts or picks another port. It also accepts explicit overrides, highest priority first:
--url <http://127.0.0.1:PORT/mcp>and--token <token>on the command line;- the
DSH_MCP_URLandDSH_MCP_TOKENenvironment variables; - otherwise
~/.dsh/mcp-bridge.json(or$DSH_HOME/mcp-bridge.json).
initialize is answered locally by the proxy; everything else is forwarded. While the app is down the proxy stays alive and answers locally with a -32000 error, and it reconnects by itself: it re-reads the discovery file on every attempt with jittered exponential backoff (500 ms base, capped at 15 s), and after a reconnect it emits notifications/tools/list_changed and notifications/resources/list_changed.
Forwarding budgets and replay. The proxy forwards with a 60 s budget by default (DSH_MCP_REQUEST_TIMEOUT_MS), and for the two blocking tools — dsh_send_message with wait: true and dsh_wait_session — it derives the budget from that call's own timeoutMs plus 30 s, so a legitimate 10-minute wait never trips the proxy (DSH_MCP_MAX_FORWARD_TIMEOUT_MS caps it at 15 min). A request that fails is only re-sent after a reconnect when re-sending cannot duplicate a side effect: tools/list, resources/*, prompts/list and ping are replayed, while tools/call is replayed only when the request provably never ran (connection refused, or an unknown transport session answered with HTTP 404). If a tools/call times out or dies ambiguously, the proxy returns a -32002 error saying the call may already have run and was therefore not retried — a duplicated dsh_send_message would appear twice in the session. Replays are capped at two per request.
Option B — Streamable HTTP directly
Read url and token from the discovery file and send them yourself:
POST http://127.0.0.1:19830/mcp
Authorization: Bearer <token>
Content-Type: application/json
Accept: application/json, text/event-stream
initialize returns an mcp-session-id response header; send it back on later requests (DELETE /mcp ends the session). After initialize, the MCP-Protocol-Version request header is validated against the revisions the server speaks (2025-06-18, 2025-03-26, 2024-11-05): anything else answers 400 with a JSON-RPC error, while a missing header is accepted for older clients. A request that runs longer than 8 s and accepts text/event-stream is answered as a single SSE message event kept alive with comment frames.
The discovery file
~/.dsh/mcp-bridge.json (override the directory with DSH_HOME), written atomically with mode 0600:
| Field | Meaning |
|---|---|
version | Discovery record version (currently 1). |
pid | Host process id. |
instanceId | UUID of this bridge instance. |
dshVersion | DSH_VERSION of the Host process, when set. |
host, port | Bound loopback address and the actual port (an ephemeral one after a failed bind). |
url | http://<host>:<port>/mcp. |
token | Bearer token for every /mcp request. |
startedAt | ISO timestamp of publication. |
running | true while this instance serves; false after a clean unload (stoppedAt is added then). |
Two properties matter to clients:
- The token survives restarts. An explicit
tokenconfig wins; otherwise the token already in the discovery file is reused; otherwise 32 random bytes are minted. - Teardown is conditional. On unload the record is only touched when its
instanceIdstill belongs to the retiring instance, so a hot reload cannot delete the record a newer instance just wrote.
GET /healthz is unauthenticated liveness (pid, instanceId, bound port, session count, uptime, server name/version). Every other request needs the bearer token, a loopback Host header (127.0.0.1:<port>, localhost:<port>, [::1]:<port>), and — when an Origin header is present — a loopback origin.
Interaction modes
Approvals and questions are claimed by the bridge or delegated to the desktop window according to a mode bound per root session. Unbound sessions use the row's interactionMode.
| Mode | Approvals | Questions |
|---|---|---|
auto (default) | MCP when no desktop client is attached, or while an MCP wait owns the session; otherwise the desktop window | Same rule |
mcp | Suspended by the bridge until dsh_respond_interaction | Same |
ui | Delegated — the desktop window asks | Same |
auto-approve | Granted as allowed-once, nobody is asked | Falls back to the auto rule |
Two honest caveats, both visible in the gate:
auto-approvecovers approvals only. It never guesses a multiple-choice answer, so questions still followautoand may land in the desktop window.- A session whose approval policy is
neverrejects the tool before any approval listener runs, soauto-approvecannot turn that rejection into a grant.
dsh_set_interaction_mode binds one session (and its subagents) to a mode; the mode default clears the binding.
Tool catalog
The bridge registers 23 tools; exposeSubagents (default on) adds three more, for 26. Every tool returns plain JSON, and a failure comes back as an isError tool result with a stable code (SESSION_NOT_FOUND, SERVICE_UNAVAILABLE, UNKNOWN_INTERACTION, BAD_REQUEST, …).
Workspaces and sessions
dsh_list_workspaces— list workspaces with directory, title, session ids, and directory status.dsh_create_workspace— register a workspace for an existing directory (reuses the registration when the directory is already owned).dsh_list_sessions— list visible sessions, newest activity first; optional contentquery,workspaceId, subagent inclusion, projection reads,limit.dsh_get_session— one session in detail: passive state, projections, workspace, live model, interaction mode, and every pending interaction.
Lifecycle
dsh_create_session— create a session in a workspace or a barecwd, then optionally title it and apply a model, permission preset, plan mode, or interaction mode.dsh_fork_session— fork at an optional inclusive event boundary (omitatSeqfor the latest completed turn).dsh_rename_session— rename one session.dsh_archive_session— archive (stopping running work), unarchive, pin, or unpin a session.
Configuration
dsh_list_capabilities— model catalog, agent presets, permission presets, and per-session slash commands and current permission preset.dsh_configure_session— change a session's model, permission preset, plan mode, working directory, or interaction mode; plan and permission go through the same/planand/permissioncommands the UI uses.
Prompts and history
dsh_send_message— send a user message (text and/or base64 images) withmode: queue|steer;waitdefaults totrueso calls block until the turn settles (idle), an interaction needs a decision (input-required), or the budget expires (timeout, returningturnSettled: false+ amonitoringfollow-up directive). Passing explicitwait: falsereturnsreason: "queued"withturnSettled: falseand a mandatorydsh_wait_sessiondirective.dsh_wait_session— wait foridle(turnSettled: true) /input-required/timeoutand return output produced afterafterSeq, looping wheneverturnSettledis false.dsh_read_events— one chronological page of history as compact records (paging withbeforeSeq/throughSeq), optionally of a subagent child log.dsh_cancel_session— cancel the active turn without dropping queued input; reportsturnSettled, because a cancelled turn can still be winding down.dsh_manage_queue— remove, steer, or edit one still-pending queued prompt; steering can resume the turn, so the result reportsturnSettled.dsh_list_commands— the slash commands this session can run.dsh_run_command— execute one slash-command line, e.g./compactor/plan off; a command can resume the model (e.g./plan <message>), so the result reportsturnSettled.
Interactions
dsh_list_pending_interactions— everything blocked on a human: interactions suspended by this bridge, events the desktop window is showing, and timed questions that already expired into acontinuedstate.dsh_respond_interaction— answer one suspended approval (outcome:allowed-once|rejected|cancelled) or question (answers, or plan-reviewapprove/feedback, or single-questionselected/custom, orcancel), or onecontinuedquestion bysessionId+callId. A continued question is answered with each question's own id (the tool looks the open call up for you; a multi-question call needs a fullanswersbatch, and a continued question cannot be cancelled — cancel the turn instead).dsh_set_interaction_mode— bind who answers for a session and its subagents;defaultclears it.
Jobs
dsh_list_jobs— background jobs of one session, or every visible job.dsh_read_job_output— a job's state and output, optionally from a byte offset.dsh_kill_job— request cancellation of one background job.
Subagents (only when exposeSubagents is on)
dsh_list_subagents— the subagent tree below a session (id, path, depth, mode, activity) without resuming a child.dsh_prompt_subagent— message a continuable subagent child (queueorsteer); always returnsturnSettled: falsewith adsh_list_subagentsdirective, because the child runs asynchronously.dsh_interrupt_subagent— interrupt a child's running work (parked inbox kept); while the child still reportsrunning, the result carriesturnSettled: falseand the samedsh_list_subagentsdirective.
Two resources complement the tools: dsh://status and dsh://workspaces, plus the template dsh://sessions/{sessionId}/summary.
Configuration
The row accepts these keys. Validation never throws: an unusable value is replaced by its default and logged once as a warning at activation.
| Key | Default | Behaviour |
|---|---|---|
port | 19830 | Integer 0–65535; 0 asks the OS for a free port. If binding the configured port fails, the plugin logs a warning and retries on an ephemeral port, then publishes the real one. |
host | 127.0.0.1 | Loopback only: 127.0.0.1, ::1, localhost are accepted (localhost and ::1 are normalised to 127.0.0.1); anything else is refused and forced to 127.0.0.1. |
token | generated | Explicit bearer token; must be hex, at least 16 characters. Omitted or invalid means "reuse the persisted token, else mint 32 random bytes". |
interactionMode | auto | One of auto, mcp, ui, auto-approve; the fallback for sessions without a binding. |
maxWaitMs | 600000 | Ceiling for one dsh_send_message / dsh_wait_session wait, 1000–3600000. |
defaultWaitMs | 30000 | Wait budget when the caller omits timeoutMs, 1000–3600000, additionally clamped to maxWaitMs. |
discoveryPath | $DSH_HOME/mcp-bridge.json | Absolute path of the published record. |
statePath | $DSH_HOME/mcp-bridge-state.json | Absolute path of the per-session interaction-mode bindings (mode 0600). |
exposeSubagents | true | Whether the three subagent tools are advertised. |
The row inserted by cordis.patch.yml:
- insert:
- id: dsh-mcp-bridge
name: '@local/dsh-mcp-bridge'
config:
port: 19830
interactionMode: auto
A profile patch targets the same row by id. config is replaced wholesale, so restate every field the row needs:
- id: dsh-mcp-bridge
config:
port: 19900
interactionMode: mcp
maxWaitMs: 1800000
Monitoring contract
Every tool that can leave work running reports the same two fields, so a calling agent never has to guess whether it may stop:
| Field | Meaning |
|---|---|
turnSettled | true only when the session has no running turn, no queued prompt, and no pending input/interaction. |
monitoring | Present only when turnSettled is false: { required: true, reason, nextTool, nextArgs, instruction }. reason is one of running, queued, timeout, input-required, responded, subagent-queued, subagent-interrupted. |
It is carried by dsh_send_message (including wait: false → reason: "queued"), dsh_wait_session, dsh_get_session, dsh_respond_interaction, dsh_run_command, dsh_manage_queue, dsh_cancel_session, dsh_prompt_subagent, and dsh_interrupt_subagent. The rule is the same everywhere: when turnSettled is false, do not report completion — call monitoring.nextTool with monitoring.nextArgs (usually dsh_wait_session with the returned cursor, or dsh_list_subagents for a subagent) until reason is "idle". The server advertises the same rule in initialize.instructions, and every affected tool description repeats it.
Design notes and limits
- Zero runtime dependencies. There is no
@deepseek-ai/*dependency and nonode_modules, so the profile'snode_modules/@deepseek-aistays clean; onlysessionControlleris a hard injection, every other service is read throughctx.get()at call time and reported asSERVICE_UNAVAILABLEwhen the profile lacks it. - The wire protocol lives in
src/. JSON-RPC dispatch (src/mcp-server.js), Streamable HTTP with SSE keep-alive for long calls (src/http-server.js), and the tool schemas (src/mcp-tools.js) are implemented here, not delegated to the official MCP SDK. - Mode bindings are not session data. Per-session modes live in
~/.dsh/mcp-bridge-state.json(mode0600) and never in a session log, and the plugin writes no custom session-log event types. - Long waits block the HTTP call.
dsh_send_message(wait: true)keeps the request open until the turn settles, so a client with its own short tool timeout must raise that too. The bundled proxy already scales its budget from the call'stimeoutMs(see Forwarding budgets and replay), but the MCP client's own timeout is outside its control. GET /mcpanswers 405. There is no server-initiated stream, so a GET/HEAD on the endpoint is refused withAllow: POST, DELETE, OPTIONS;DELETE /mcpends a transport session.- Requests are capped at 32 MiB (
413beyond that), idle transport sessions are dropped after two hours, and a request body that is not JSON withContent-Type: application/jsonis refused with415.
Verify
From this directory:
node --test test/
pnpm run check # or: npm run check — chains node --check over every source file
node --test test/ is the package test script. On the Node 22.23.2 used for this checkout the directory argument was resolved as a module and failed; node --test test/*.test.js and a bare node --test both ran the whole suite green.
Live checks, with the plugin row active:
curl -sf http://127.0.0.1:19830/healthz
curl -i -X POST http://127.0.0.1:19830/mcp -H 'content-type: application/json' -d '{}'
The first prints the health JSON; the second must answer 401 unauthorized — an unauthenticated body is rejected before it is parsed.
Layout
dsh_agy_input/
├── index.js plugin entry: one ctx.effect owns listener, gate, discovery
├── cordis.patch.yml bundle patch inserting the dsh-mcp-bridge row
├── package.json manifest, engines, exports, test/check scripts
├── icon.svg plugin icon
├── locale/
│ ├── en.json Plugin Manager title, description, detail path
│ └── zh.json Chinese title and description
├── docs/
│ └── DETAIL.md plugin detail page
├── bin/
│ └── dsh-mcp-stdio.mjs stdio ⇄ HTTP MCP proxy with reconnect
├── src/
│ ├── config.js row-config normalisation, interaction modes
│ ├── discovery.js discovery + state files, token reuse, retirement
│ ├── interaction-gate.js approval/question waterfalls, modes, settlement
│ ├── dsh-ops.js Host service operations behind the tools
│ ├── mcp-server.js JSON-RPC 2.0 dispatch and MCP envelopes
│ ├── mcp-tools.js the tool/resource catalog and schema validation
│ └── http-server.js loopback Streamable HTTP transport, auth, SSE
└── test/ (development only — not shipped in the npm tarball)
├── helpers.js mock Cordis context and waterfall dispatch
├── config.test.js defaults, clamping, loopback enforcement
├── discovery.test.js publication, token reuse, conditional retirement
├── interaction-gate.test.js mode decisions, answers, abort/unload settling
├── dsh-ops.test.js tool handlers against mocked services
├── mcp-e2e.test.js endpoint auth, protocol, SSE, resources, close order
├── index.test.js activation, discovery, teardown
├── stdio-proxy.test.js proxy forwarding, SSE, offline reconnect
└── proxy-forward-policy.test.js derived wait budgets, no replay on unknown outcome
Related plugins
archify (deepseek-harness)
tt-a1i/archify
WeKnora (dsh-weknora)
tencent/weknora
next-ai-draw-io (dsh-plugin)
dayuanjiang/next-ai-draw-io
weknora
tencent/weknora