dsh-mcp-loader
Lazy-loading MCP tools for DeepSeek Harness (DSH):
each multi-tool MCP server is represented by one loader tool (default mcp_<server>), and a server's real
tools enter the model context only after the loader is called. With many MCP servers installed, this removes the
fixed cost of every tool schema being present in every request — and keeps the visible tool list small enough
that the model picks the right tool.
How it works
Initial tool list: mcp_notes, mcp_browser, mcp_desktop, ... (one loader per server)
↓ model calls mcp_notes({})
→ "ok" the next request exposes mcp__notes__search, mcp__notes__create, ...
↓ model calls mcp_notes({}) again
→ "ok (20 tool(s) hidden)" those tools leave the context
↓ a third call loads them again
The loader is a toggle: call once to load, call again to hide, call a third time to load again —
no separate "unload tool" occupies a slot. Single-tool servers (e.g. a lone codegraph_explore) are detected
at startup and stay resident without a loader.
Registration model
- Tool schemas are projected when the prompt is assembled (
ctx.systemPrompt.tools(...)), so tools registered
inside one tool call appear in the model's next step of the same turn — no extra round trip.
- Startup registers only loaders (no process spawned). A one-time probe may connect
auto/eager servers to
count their tools: servers with ≤ singleToolThreshold tools become resident and their loader is removed;
mode: lazy servers never participate in the probe and are not spawned at boot.
- Registration is deployment-wide (global), consistent with the official
dsh-mcp-client, because
ctx.tools.restrict() only filters inherited tools and rejects names that are not globally registered —
per-agent hiding (hiddenTools) is built on top of global registration.
Features
- Per-server loader toggle — load, hide, reload, with a visible result message (
ok, ok (N tool(s) hidden)).
- Modes —
auto (probe once at startup), lazy (always behind a loader, never probed), eager (always resident, no loader).
hiddenTools — mask specific tools per agent after a server loads (restrict({ deny })), for every existing
agent and for agents created later; masks are per-agent visibility only, the tools stay globally registered.- Description engineering — per-server
description, descriptionPreset, per-tool toolDescriptions
overrides, and parameter-description truncation (maxParameterDescriptionChars), so the model-facing text
says what the tool does and when to use it.
- Resilience — atomic registration (any failure rolls the server back to zero tools), shared concurrent
attempts,
list_changed resync (full-generation replace), raw tools/call (skips outputSchema validation of
structuredContent, same as the official client), transport-failure discard-and-reconnect on next call.
- Transports —
stdio (spawn command/args, env merged into the SDK default environment) and
streamable-http (url/headers).
- Config fail-fast — unknown preset or invalid server name (
[A-Za-z0-9_-]{1,32}) fails plugin mount with a
named field.
Install
npm install # build/test locally
npm run build # tsc → lib/
npm test # real-link e2e: real cordis ctx + dsh-tools ToolRuntime + real MCP stdio subprocesses
Then register the plugin in your profile (id mcp-loader, package dsh-mcp-loader) and add your servers:
- id: mcp-loader
name: dsh-mcp-loader
config:
servers:
notes:
description: "Search, read, create and organize personal notes. Use when the task involves the user's notes."
command: npx
args: ['-y', 'mcp-remote', 'https://example.invalid/mcp']
desktop:
description: "Control the real desktop ..."
mode: lazy
command: npx
args: ['-y', 'example-desktop-mcp']
Configuration
| Field | Default | Meaning |
|---|
servers | {} | Server table; the key is the namespace of mcp__<server>__<tool> |
servers.<n>.description | — | Loader description body: what it can do + when to use it |
servers.<n>.mode | auto | auto / lazy (always loader) / eager (always resident) |
servers.<n>.loaderName | mcp_<server> | Model-visible loader name |
servers.<n>.hiddenTools | — | Tool names (raw or mcp__s__t) masked per agent after load |
servers.<n>.toolDescriptions | — | Per-tool description overrides |
servers.<n>.descriptionPreset | — | Built-in description tables (desktop-touch) |
servers.<n>.maxParameterDescriptionChars | 0 | Truncate parameter descriptions (preset may imply one) |
servers.<n>.transport | stdio | stdio or streamable-http |
servers.<n>.command/args/env/cwd | — | stdio process to spawn |
servers.<n>.url/headers | — | streamable-http endpoint and extra headers |
servers.<n>.toolCallTimeoutMs | 60000 | Per tools/call timeout |
connectTimeoutMs | 30000 | Connection handshake timeout |
singleToolThreshold | 1 | auto mode: servers with ≤ this many tools stay resident |
loaderHint | Call to load this MCP server's tools; call again to hide them. | Appended to every loader description |
Known limitations
- Granularity is per server, not per tool (one loader per server).
- Startup probing is a snapshot: a server that later grows past the threshold stays revealed until restart (pin it with
mode: lazy).
- Images/audio become
[image image/png] text placeholders; only tools are bridged — MCP resources/prompts/
progress and task-typed tools are not supported (consistent with dsh-mcp-client).
- No active reconnect backoff; reconnection happens on the next call.
Ecosystem position
dsh-mcp-loader is one of several DSH plugins that keep large MCP tool catalogs out of every request
(compare dsh-mcp-lazy, dsh-capability-menu, dsh-tool-folder, dsh-mcp-lens, dsh-tool-search).
Its differentiators: per-server loader toggles, per-agent hiddenTools masking, and model-facing description
presets — plus self-owned connections (stdio and streamable-http) instead of wrapping another MCP client.
License
MIT
