Skip to main content
G

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-bridge

README

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 its command, 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 the dsh-mcp-bridge row is present and enabled.
  • CLI: dsh plugin --profile <profile> add dsh-mcp-bridge-server, then restart the app (or the dsh web process) 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:

  1. Install the directory through Plugins → Add plugin, or through the plugin_manager tool with install_bundle and the absolute path of this checkout as the target.
  2. Confirm the plugin row dsh-mcp-bridge (@local/dsh-mcp-bridge in 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

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_URL and DSH_MCP_TOKEN environment 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:

FieldMeaning
versionDiscovery record version (currently 1).
pidHost process id.
instanceIdUUID of this bridge instance.
dshVersionDSH_VERSION of the Host process, when set.
host, portBound loopback address and the actual port (an ephemeral one after a failed bind).
urlhttp://<host>:<port>/mcp.
tokenBearer token for every /mcp request.
startedAtISO timestamp of publication.
runningtrue while this instance serves; false after a clean unload (stoppedAt is added then).

Two properties matter to clients:

  • The token survives restarts. An explicit token config 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 instanceId still 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.

ModeApprovalsQuestions
auto (default)MCP when no desktop client is attached, or while an MCP wait owns the session; otherwise the desktop windowSame rule
mcpSuspended by the bridge until dsh_respond_interactionSame
uiDelegated — the desktop window asksSame
auto-approveGranted as allowed-once, nobody is askedFalls back to the auto rule

Two honest caveats, both visible in the gate:

  • auto-approve covers approvals only. It never guesses a multiple-choice answer, so questions still follow auto and may land in the desktop window.
  • A session whose approval policy is never rejects the tool before any approval listener runs, so auto-approve cannot 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 content query, 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 bare cwd, 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 (omit atSeq for 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 /plan and /permission commands the UI uses.

Prompts and history

  • dsh_send_message — send a user message (text and/or base64 images) with mode: queue|steer; wait defaults to true so calls block until the turn settles (idle), an interaction needs a decision (input-required), or the budget expires (timeout, returning turnSettled: false + a monitoring follow-up directive). Passing explicit wait: false returns reason: "queued" with turnSettled: false and a mandatory dsh_wait_session directive.
  • dsh_wait_session — wait for idle (turnSettled: true) / input-required / timeout and return output produced after afterSeq, looping whenever turnSettled is false.
  • dsh_read_events — one chronological page of history as compact records (paging with beforeSeq/throughSeq), optionally of a subagent child log.
  • dsh_cancel_session — cancel the active turn without dropping queued input; reports turnSettled, 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 reports turnSettled.
  • dsh_list_commands — the slash commands this session can run.
  • dsh_run_command — execute one slash-command line, e.g. /compact or /plan off; a command can resume the model (e.g. /plan <message>), so the result reports turnSettled.

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 a continued state.
  • dsh_respond_interaction — answer one suspended approval (outcome: allowed-once | rejected | cancelled) or question (answers, or plan-review approve/feedback, or single-question selected/custom, or cancel), or one continued question by sessionId + 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 full answers batch, and a continued question cannot be cancelled — cancel the turn instead).
  • dsh_set_interaction_mode — bind who answers for a session and its subagents; default clears 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 (queue or steer); always returns turnSettled: false with a dsh_list_subagents directive, because the child runs asynchronously.
  • dsh_interrupt_subagent — interrupt a child's running work (parked inbox kept); while the child still reports running, the result carries turnSettled: false and the same dsh_list_subagents directive.

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.

KeyDefaultBehaviour
port19830Integer 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.
host127.0.0.1Loopback 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.
tokengeneratedExplicit bearer token; must be hex, at least 16 characters. Omitted or invalid means "reuse the persisted token, else mint 32 random bytes".
interactionModeautoOne of auto, mcp, ui, auto-approve; the fallback for sessions without a binding.
maxWaitMs600000Ceiling for one dsh_send_message / dsh_wait_session wait, 1000–3600000.
defaultWaitMs30000Wait budget when the caller omits timeoutMs, 1000–3600000, additionally clamped to maxWaitMs.
discoveryPath$DSH_HOME/mcp-bridge.jsonAbsolute path of the published record.
statePath$DSH_HOME/mcp-bridge-state.jsonAbsolute path of the per-session interaction-mode bindings (mode 0600).
exposeSubagentstrueWhether 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:

FieldMeaning
turnSettledtrue only when the session has no running turn, no queued prompt, and no pending input/interaction.
monitoringPresent 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 no node_modules, so the profile's node_modules/@deepseek-ai stays clean; only sessionController is a hard injection, every other service is read through ctx.get() at call time and reported as SERVICE_UNAVAILABLE when 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 (mode 0600) 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's timeoutMs (see Forwarding budgets and replay), but the MCP client's own timeout is outside its control.
  • GET /mcp answers 405. There is no server-initiated stream, so a GET/HEAD on the endpoint is refused with Allow: POST, DELETE, OPTIONS; DELETE /mcp ends a transport session.
  • Requests are capped at 32 MiB (413 beyond that), idle transport sessions are dropped after two hours, and a request body that is not JSON with Content-Type: application/json is refused with 415.

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