dsh-project-mcp-bridge

English | 中文

TL;DR — Let each project declare its own MCP servers. Drop a
.dsh/mcp.json into a project root; every session of that project then
has those servers' tools (mcp__<serverName>__<toolName>), and editing
the file takes effect live — no new session, no restart.

It is a client bridge (consumes MCP servers). Not an MCP server, not
an official DeepSeek package.

30-second demo

// MyProject/.dsh/mcp.json
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" }
    }
  }
}

Then, in any session opened in MyProject, the model can directly call
mcp__github__create_issue etc. — the same mcpServers JSON shape used by
Claude Code, Cursor and VS Code. Save the file again later and running
sessions pick the change up within ~1 s.

Install once: dsh plugin --profile web add dsh-project-mcp-bridge (one
restart), or see Installation for the restart-free dev
path.

How it works

agent created (agent/created)
  -> read <session cwd>/.dsh/mcp.json
  -> for each server entry:
       - if a preset/host MCP row already provides the same serverName
         and the entry has no "override": true  -> skip (log explains why)
       - else one-shot SCHEMA SYNC: connect (stdio spawn or
         streamable-http) + list tools + register each as
         mcp__<serverName>__<rawName> into the AGENT scope layer only
         (project > preset > host) + close again
  -> no connection is kept: an idle session holds no child process

first call to a server's tool (execute)
  -> the agent's controller checks its per-server connection
  -> absent -> LAZY CONNECT ("connecting..." is logged; this is the
     first-call latency) -> call
  -> every call re-arms a per-connection idle timer (default 5 min);
     on fire the connection closes and the child process is released;
     the next call reconnects transparently
  -> if the connection dies (onclose), this agent drops it and the next
     call reconnects — no broadcast, no shared state

Connections are per agent, never pooled: N sessions calling the same
server run N independent processes (isolation over sharing). Sessions that
never call a server hold no process at all.

Installation

The package is a profile bundle: install with the dsh CLI, no manual
patching.

dsh plugin --profile web add dsh-project-mcp-bridge

dsh plugin runs pnpm in the profile directory, then reconciles
dsh.profile.bundles: the package declares dsh.bundle.patch, so it joins
the profile's bundle layers automatically. The bundle's own
cordis.patch.yml supplies the plugin row — nothing to add by hand.

Restart dsh web once after installing: bundle layers are composed at
startup (only the user patch layer and settings.yaml are hot-reloaded).
After that, .dsh/mcp.json changes are hot (see Config hot-reload).

Restart-free dev path (hot install)

If you iterate on this plugin itself and want changes live without
restarts, install it as a user patch row instead of a bundle. The row
references the package by name (resolved from the profile's
node_modules), so it is portable and hot:

cd ~/.dsh/profiles/web
pnpm add dsh-project-mcp-bridge          # package into node_modules (no reconcile)

Then append to ~/.dsh/profiles/web/cordis.patch.yml:

- insert:
    - id: dsh-project-mcp-bridge
      name: 'dsh-project-mcp-bridge'     # package name, NOT a file:// path

The user patch layer is hot-reloaded (~4 s), so the row activates without
a restart. Note: do NOT use dsh plugin add for this path — it would also
register the bundle and duplicate the row after the next restart. Prefer
the bundle install for normal use; this path is for local iteration.

Project config

Create .dsh/mcp.json at the project root (the file's presence is the
opt-in; sessions of projects without it are untouched):

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" },
      "idleTimeoutMs": 300000
    },
    "local-api": {
      "url": "http://localhost:3000/mcp",
      "headers": { "Authorization": "Bearer ${MCP_TOKEN}" },
      "override": true
    }
  }
}

Fields (same names as dsh-mcp-client)

${NAME} placeholders in env/headers values are expanded from the
host process environment.

Conflict semantics (project vs. preset/host MCP)

• Tools register into the agent scope layer; the layered registry
  shadows same-named tools from the preset layer and the global layer —
  visibility priority is project > preset > host.
• A serverName already provided by a preset/host row is skipped by
  default (one live connection per server). Set "override": true to
  force the project connection instead (double connection accepted,
  project tools win).
• Override does not disable the upper layers. The project connection is
  added on top: the upper (host/preset) connections stay alive, and the
  agent-layer copy shadows same-named tools (layered registry), so the
  model actually calls the project connection. The tool names carry no
  origin marker — the plugin logs
  ... shadows upper-layer registration(s); upper connections stay alive
  when an override registers over existing upper registrations; process
  count is the other way to verify.
• Different serverNames or different tool names coexist freely.
• Note — two bridges, two philosophies: between official
  dsh-mcp-client instances (host rows, preset rows), a duplicate
  serverName is process-wide unique and fails the mount ("pick a
  unique serverName") — that bridge prefers fail-loud over silent
  shadowing. This plugin, when its project config collides with an upper
  layer, skips instead, so the project session still starts. In
  practice: project vs host/preset duplicates → skipped (this plugin);
  preset vs host duplicates among dsh-mcp-client rows → rename one.

Config hot-reload

Saving .dsh/mcp.json re-resolves the config for every running session
of that project and fully rebuilds each session's project MCP surface:

• added server → schema sync + register tools (running sessions gain them)
• removed server → unregister tools + close its connection
• changed server → full rebuild — unregister everything, close all
  connections, re-read, re-register. No fingerprint diffing: a change simply
  rebuilds. Same serverName keeps the same public tool names, so recorded
  tool calls stay replayable
• deleted config → all project MCP tools unload

No new session needed. The file is polled (fs.watchFile, ~500 ms) with a
300 ms debounce, fanned out to every live session of the project. An
in-flight tool call on a server being reconfigured may be interrupted by the
rebuild.

Connection death (v4): if a server's process dies, the SDK's onclose
fires and that agent drops its dead connection; the next call reconnects
automatically (lazy) — no restart, no new session, no config change. Each
agent is self-managed: nothing is broadcast, so a death in one session never
disturbs another. A reconnect that fails surfaces as a tool error; the next
call retries. Note: after a reconnect, the server's internal dependencies
(e.g. a browser connection) may take a few more seconds to become ready —
calls in that window can fail with the server's own error; this is server
behavior, not a bridge defect.

Idle disconnect: connections close after idleTimeoutMs without a call
(default 5 min; per-server configurable, 0 = never). An idle session holds
no child process; the next call reconnects transparently (only latency).

Lazy connect caveat: tool schemas only exist on the server, so session
creation performs a brief one-shot schema sync per accepted server (connect

• list tools + register + close). Sessions that never call a server pay only
  this brief spawn; no connection is kept afterwards. If the schema sync fails
  (server down at creation), that server's tools are not registered until the
  next config change or a new session.

Environment scrubbing (privilege reduction)

MCP children are spawned with the official scrubbedParentEnv(): the
ambient environment minus credential-shaped names (anything matching
KEY|PASSWORD|SECRET|TOKEN) and minus stale DSH_* names. PATH, HOME
and locale survive, so children run normally; secrets that merely happen
to be in the host environment are NOT inherited. Only the entry's explicit
env is added back. This is not a sandbox: a malicious config can still
execute code as your user and read your files (see Trust model).

Trust model ⚠️

.dsh/mcp.json contains executable content — the same trust model as
package.json scripts. A git clone can bring its own .dsh/mcp.json
(just as it can bring a malicious postinstall), and opening the project
will run it when a session is created. Only open projects from sources you
trust. The plugin reduces blast radius (scrubbed env, auditable logs) but
does not and cannot make untrusted projects safe.

Logging

• ctx.logger (host stdout — not persisted by this deployment)
• ~/.dsh/logs/dsh-project-mcp-bridge/dsh-project-mcp-bridge.log
  (append-only; every step — config read, skip reason, connect, tool
  registration, close — is recorded with a timestamp and the project path)

Limitations

• Resources and prompts from MCP servers are not bridged (tools only).
• Connections are per agent, never pooled: N sessions calling the same
  server = N processes. Heavy servers (e.g. chrome-devtools) cost one
  process per active session — the idle timeout keeps unused ones short-
  lived. Session creation also pays one brief schema-sync spawn per server.
• Streaming/task-based MCP execution is not supported (call only).

Further reading

• Design notes: DSH philosophy and this plugin's alignment ·
  设计笔记（中文） — why DSH is layered the way
  it is, its trust model, the hot-reload boundary, and why project-level MCP
  is a plugin's job.