dsh-mcp-lazy

A lazy MCP gateway for DeepSeek Harness. It puts one
tool in front of the model instead of N MCP tool schemas: servers start on first use, idle
out again, and their tool metadata is cached on disk so search and describe never spawn
anything.

Why

@deepseek-ai/dsh-mcp-client connects every configured server at startup and registers every
one of its tools as a native tool. As its own README puts it, tool descriptions and input
schemas "enter every request while the tools are registered". A handful of servers therefore
costs thousands of tokens on every request and one resident child process each — whether or
not the model ever calls them.

This plugin keeps the model-facing surface at exactly one tool whose schema never changes,
discovers tools on demand from a disk cache, and only spawns a server when a call needs it.

The numbers

Measured against chrome-devtools-mcp@1.6.0 (29 tools), both sides rendered the same way —
JSON bytes of the tool definitions, then four bytes per token:

The gateway figure is constant: configuring ten more servers does not move it, because their
schemas are read on demand rather than sent every request.

The honest counterweight. The gateway costs a fixed 1525 bytes, so it wins only when a
server's rendered tool definitions exceed that. The bundled fixture offers 7 small tools and
the saving drops to 1.7%. A server with a couple of tiny tools would make the gateway a net
loss. Measure your own before assuming:

pnpm run measure:savings                                          # local fixture
node scripts/measure-token-savings.mjs --npx

Install

dsh plugin --profile  add dsh-mcp-lazy

Works with the DeepSeek Harness 0.1.5-rc and 0.2.0-rc lines (verified against
0.2.0-rc.2); the package's peer ranges declare exactly that.

That installs the package into the profile and registers its bundle patch, which inserts the
mcp-lazy row. Then give it your servers in the profile's cordis.patch.yml:

- id: mcp-lazy
config:
servers:
- serverName: chrome
transport: stdio
command: npx
args: ['-y', 'chrome-devtools-mcp@1.6.0']
lifecycle: lazy
- serverName: docs
transport: streamable-http
url: http://127.0.0.1:3000/mcp

Restart the profile. Every field is documented in docs/configuration.md.

Moving servers off @deepseek-ai/dsh-mcp-client

Every writer of MCP configuration in this ecosystem emits a @deepseek-ai/dsh-mcp-client row:
the config-manager panel hardcodes that package name, @hyzyn/dsh-codegraph writes a managed
row, and a hand-written config follows the same convention. Such a row registers each MCP tool
as a real tool, so its schemas enter every request — and a server listed in both places
cancels the saving this plugin exists for, with no error and nothing to notice. (The mcp({})
status output does warn you — for any server the other plugin serves natively, whether or not
this one has it too — which is how you usually find out.)

adopt does the move for you:

dsh-mcp-lazy-adopt                 # dry run: prints the plan, writes nothing
dsh-mcp-lazy-adopt --write         # applies it, with a timestamped backup of each file

Or, without leaving the session, as a slash command:

/mcp-adopt                         # dry run
/mcp-adopt apply                   # writes

The command drives the same CLI, so the plan, the backups and the write are one code path; a
successful apply is followed by a re-plan whose result is shown to you, so the answer to "did
it work?" is evidence rather than an assurance. It still requires the human to type it: nothing
runs at plugin startup.

It reads what is actually mounted (dsh --profile --dump-config, so all four patch layers
are composed), marks each original row disabled: true in place, and appends the server to
this plugin's servers list. Nothing else in the file is touched — comments, blank lines and
!!js expressions are preserved byte for byte — and a row it cannot move safely is reported
with a reason instead of being guessed at. Run it while the host is stopped: the web profile
reloads its patch layer live, and dsh-config-manager rewrites the same file from its own
state.

Check the blast radius before you apply. The native row usually lives in the home patch,
which every profile reads, while this plugin's row lives in one profile's patch. Disabling the
former therefore takes that server away from every other profile as well — and those profiles
have no gateway to receive it, so they simply lose the capability. The plan names them:

⚠ the row being disabled lives in the home layer ~/.dsh/cordis.patch.yml, which every profile reads.
3 other profile(s) do not mount dsh-mcp-lazy, so they would lose codegraph with no replacement:
default, dsh-tui, headless.
Mount dsh-mcp-lazy in those profiles, or move the row into web's own layer, if they need it.

If any of them need the server, mount this plugin there too (or move the row) before applying.

A server that does move arrives with only the fields this plugin implements. Two of the other
plugin's fields are not implemented here — reconnect and failOnStartupError — and
carrying them over is an error rather than a no-op, so a row that sets either one is reported as
unsupported-field and left exactly where it is: no half-move, and no load failure from a
setting that would look configured and do nothing. A misspelled field name is reported the same
way. The per-row id is dropped, because it names the loader row rather than the server.

What the model sees

One tool, always the same 11 parameters:

mcp({ search: "screenshot" })          # find a tool — reads the cache, starts nothing
mcp({ describe: "take_screenshot" })   # full argument schema
mcp({ tool: "take_screenshot" })       # call it — this is what spawns the server
mcp({ tool: "echo", server: "docs" })  # disambiguate a name two servers share
mcp({ connect: "chrome" })             # connect and refresh the cache, without calling
mcp({ instructions: "chrome" })        # the server's own usage notes
mcp({})                                # status: tool count, connection state, cache age

Seven of the 11 are the actions above. The other four shape a search and are
never needed for anything else:

That one tool is the whole model-facing surface by default. directTools is
the opt-in that promotes chosen server tools into real native tools instead —
see docs/configuration.md
for what it accepts, and why the default is the cheap choice.

Documentation

Known limitations

The v1 boundary, stated plainly:

• Tools only. No MCP resources, prompts, sampling, or elicitation. Only tools/list_changed
  is subscribed.
• No OAuth. Authentication is a plaintext headers entry or an environment variable.
• Image and audio results are not forwarded. They are projected to a one-line metadata
  entry (type and byte count). Forwarding pixels needs attachment storage this plugin does
  not implement.
• No approval gate. MCP calls follow your DSH permission preset.
• No config interop. It reads DSH-native config only; it will not import .mcp.json,
  Cursor, Claude Code, Codex, or VS Code server lists.
• The regex guard is deliberately narrow. A 256-character cap plus a nested-quantifier
  check, which does not catch overlapping alternation like (a|aa)+ or polynomial
  backtracking like a*a*a*b. A full analyser would mean a second runtime dependency.
• No SSE or unix-socket transports. stdio and streamable-http only.
• npx is not resolved to the underlying binary, so an npx-launched server costs one
  extra Node parent process.
• A secret passed through args lands in the child's argv, where ps and
  /proc//cmdline can read it. That path exists only because some servers accept a token
  no other way; envFrom alone keeps the value out of argv.

Development

pnpm install
pnpm test          # builds, relinks the peer packages, runs 390 tests
pnpm run check     # typecheck, lint, build, then type-check the test sources

See CONTRIBUTING.md.

Star history

License

MIT — see LICENSE. The connection supervisor, transport factory, and
environment-scrubbing rules derive from @deepseek-ai/dsh-mcp-client; the single-proxy-tool
gateway, metadata cache, and weighted search ranking derive from pi-mcp-adapter. Both are
MIT; their notices are reproduced in THIRD_PARTY_NOTICES.md.