@deepseek-ai/dsh-mcp-client

English | 中文

MCP client bridge plugin: connects to external Model Context Protocol servers and registers their tools on ctx.tools, making them available to the model as native tools under server-qualified names (mcp__<serverName>__<rawName>).

Usage

One plugin instance per MCP server in cordis.yml:

- id: mcp-github
  name: '@deepseek-ai/dsh-mcp-client'
  config:
    serverName: github
    transport: stdio
    command: npx
    args: ['-y', '@modelcontextprotocol/server-github']
    env:
      GITHUB_TOKEN: !!js process.env.GITHUB_TOKEN

- id: mcp-web
  name: '@deepseek-ai/dsh-mcp-client'
  config:
    serverName: web
    transport: streamable-http
    url: http://localhost:3000/mcp
    headers:
      Authorization: !!js '`Bearer ${process.env.MCP_TOKEN}`'

The model sees mcp__github__create_issue, mcp__web__search, … — the same server-qualified shape Claude Code and Codex use. HMR hot-swaps: editing the entry triggers disconnect + reconnect without process restart; an unchanged serverName reproduces identical tool names.

Config

Tool naming

Every MCP tool has two names: the raw MCP name (sent on the wire in tools/call) and the public name mcp__<serverName>__<rawName> registered on ctx.tools. Public names are normalized to the DeepSeek function-name contract (64 chars, [A-Za-z0-9_-]); when replacement or truncation changes the name, a deterministic 12-hex-char hash of (serverName, rawName) is appended so distinct tools never collapse into one name. Names are pure functions of (serverName, rawName) — connection order, re-syncs, and other servers never rename a tool.

• Two servers publishing the same raw name (e.g. search) coexist under their namespaces.
• A duplicate serverName across live instances fails the later plugin instance at load.
• A server listing the same tool name twice is rejected as an invalid tool list.
• A foreign registration squatting on this server's namespace rolls back the whole generation (never a partial set), with a loud error.

Behavior

• On connect: plugin activation awaits listTools() and registers each tool via ctx.tools.register() under its public name before the composition starts its first turn. Initial connection, discovery, or registration failure is always logged; it rejects activation when failOnStartupError is true and otherwise activates with no tools.
• Listens for notifications/tools/list_changed → re-syncs; a fetch-phase failure keeps the previous generation registered, while a registration conflict rolls back the attempted generation and leaves no tools from that server.
• Tool execute: client.callTool({ name: rawName, arguments }, { signal }) with timeout + abort support—the public name is never sent to the server.
• Canonical success is { content: JsonValue[], structuredContent? }; complete JSON MCP blocks survive for programmatic callers. A supported advertised outputSchema validates structuredContent; unsupported schema vocabulary falls back to unconstrained JsonValue.
• Native/model rendering keeps the existing text projection: text blocks join with newlines while image, audio, resource, and unsupported blocks become placeholders.
• On disconnect/crash: the supervisor restarts the original server config with exponential backoff (reconnect.initialDelayMs doubling up to reconnect.maxDelayMs) and re-runs discovery on success — the recovered generation replaces the previous one, so tools neither duplicate nor leak. During the outage the last good generation stays registered; calls against it fail until recovery.
• Reconnection is budgeted per outage: after reconnect.maxAttempts consecutive failures the server's tools are unregistered and reconnection stops until an HMR reload or Host restart. A connection that survives past maxDelayMs resets the budget, so an occasionally-crashing server recovers indefinitely while a crash-looping one — even with briefly successful connects — still exhausts the cap instead of restarting forever.
• Reconnect states are user-visible in logs: reconnecting (warn, with attempt count and delay), recovered (info), final failure and disabled-loss (error). Disposal cancels any pending reconnect. With reconnect.enabled: false, a lost connection keeps tools registered but failing until a reload — the manual-recovery behavior.

Services consumed

Model Experience

Discovered MCP tools

What the model sees

After initial discovery succeeds, each advertised MCP tool appears as a native tool named mcp__<serverName>__<rawName> (or its deterministic normalized form), with the server-provided description and input schema. A successful re-sync — including the one after an automatic reconnect — replaces the generation; plugin disposal or an exhausted reconnect budget removes it.

Token effect

Data-dependent schema cost is paid on every request while the tools are registered. Re-sync replaces rather than accumulates schemas, and the server-qualified name adds tokens to every tool definition and call.

KV Cache effect

Prefix-stable while the discovered tool set and schemas are unchanged. A re-sync that adds, removes, renames, or changes a tool replaces definitions and may invalidate reuse from the first changed schema token; a reconnect that recovers an unchanged list reproduces identical definitions and stays prefix-stable.

Tool-call history and results

What the model sees

The public tool name and JSON arguments remain in assistant history. Text result blocks are joined with newlines into one retained Native text result; image, audio, resource, and unsupported blocks become short placeholders there. Their full JSON blocks and optional structured content remain in the execution-local canonical value, and MCP isError rejects the call through the registry's error path.

Token effect

Arguments and mapped text are retained until compaction. Binary and resource payloads are discarded rather than added to context.

KV Cache effect

Append-only; newly visible content follows the reusable request prefix and does not invalidate existing KV-cache entries.

Known Limitations and Deferred Work

• Tools are the only bridged MCP capability — Resources and Prompts have no harness consumer and are deferred.
• Startup timeout is inherited from the MCP SDK — DSH does not yet expose a connection/discovery timeout. Each initialize or paginated tools/list request uses the SDK's 60-second default, so an unresponsive server or cursor chain can delay both activation and teardown while the initial synchronization settles.
• Reconnect triggers on transport close — a crashed stdio child fires it; Streamable HTTP failures surface per request and through the SDK transport's own SSE-stream recovery, so an unreachable HTTP server is retried per call rather than respawned by the supervisor.
• Native non-text rendering is lossy — image, audio, and resource payloads become placeholders in model context even though the execution-local canonical value preserves their JSON blocks. Richer Native multimedia projection is deferred.
• Unsupported MCP output schemas are not enforced — structuredContent falls back to JsonValue when the advertised schema uses vocabulary outside the harness subset.