dsh-mcp-client-plus

An MCP client bridge for DeepSeek Harness (dsh), forked from the built-in @deepseek-ai/dsh-mcp-client and extended with the capabilities its own documentation lists as deferred.

Everything the upstream bridge does, it still does: one plugin instance per MCP server, tools registered as native mcp__<serverName>__<rawName> tools, serverName namespacing, tool-list-change refresh, and reconnect with exponential backoff.

What it adds:

	Capability	Upstream
1	OAuth 2.1 — discovery, RFC 7591 dynamic client registration, PKCE, refresh rotation, browser redirect	static headers only
2	connectTimeoutMs — bounds initialize	inherits the SDK's 60s default
3	discoveryTimeoutMs — bounds each tools/list page	passes no timeout at all
4	Secrets by environment — tokenEnv, headerEnv	raw values inlined in cordis.yml
5	maxAttempts: 0 — reconnect indefinitely	gives up permanently after 10
6	mcp_status tool — live per-server state from inside a session	log output only

---

Why these six

These are not speculative features. Each one maps to a concrete failure of the upstream bridge, and the first five were reproduced against a real harness before this fork was written.

The upstream bridge can give up permanently and never recover. On a startup failure it retries with backoff, then unregisters and logs giving up after 10 consecutive failed reconnect attempts — tools unregistered; reload the plugin or restart the Host to reconnect. Nothing self-heals, and the failure is visible only in host stderr. In the harness this was diagnosed on, five OAuth-protected servers were dead this way — valid credentials, reachable endpoints, zero tools — while the two servers without an Authorization header worked fine.

OAuth is the root cause of most of that. Because upstream accepts only static headers, an OAuth server has to be fed a token by an out-of-band bridge — commonly a config expression that shells out to another agent's credential store on every load. That path is fragile (a Keychain ACL denial is silently swallowed into an empty Bearer header), and it cannot refresh. auth: oauth removes the bridge entirely: the SDK performs discovery, registration, and refresh, and the first connect prints an authorization URL.

Timeouts were unbounded in two places. listToolsUncached passed no RequestOptions at all, so every tools/list page waited the SDK's 60-second default, and connect() did the same for initialize. A single unresponsive server could stall plugin activation for minutes. Both are now explicit and configurable.

A dead server is invisible from a session. mcp_status reports every configured server, its state, registered tool count, retry position, and last error — so "why is this tool missing" is answerable without reading host logs.

---

Install

npx -p @deepseek-ai/dsh dsh plugin --profile web add github:anthonyyu-verkada/dsh-mcp-client-plus

Then declare your servers in your profile patch (~/.dsh/profiles/web/cordis.patch.yml) and restart dsh.

The bundled cordis.patch.yml is intentionally empty: the bridge is one instance per server, so a packaged patch cannot know your servers. See the comments in that file for copy-pasteable row templates.

Quick start

OAuth-protected remote server

- insert:
    - id: mcp-linear
      name: 'dsh-mcp-client-plus'
      config:
        transport: streamable-http
        serverName: linear
        url: https://mcp.linear.app/mcp
        auth: oauth
        reconnect:
          maxAttempts: 0

On first connect the host logs an authorization URL and opens your browser. After consent the loopback listener captures the code, tokens are stored, and the tools register. Tokens refresh automatically, and rotation is persisted.

Credentials live in $DSH_HOME/.dsh/mcp-client-plus-oauth.json, mode 0600, keyed by resource-server URL. Treat that file as a secret.

Token from the environment

- insert:
    - id: mcp-tracecat
      name: 'dsh-mcp-client-plus'
      config:
        transport: streamable-http
        serverName: tracecat
        url: https://tracecat.example.com/mcp
        auth: bearer
        tokenEnv: TRACECAT_MCP_TOKEN

The token itself never appears in config. auth: none sends no Authorization header at all.

Local stdio server

- insert:
    - id: mcp-terraform
      name: 'dsh-mcp-client-plus'
      config:
        transport: stdio
        serverName: terraform
        command: /Users/you/go/bin/terraform-mcp-server
        args: [stdio]
        env:
          TFE_ADDRESS: https://app.terraform.io
          TFE_TOKEN: ''

Migrating from the built-in client

Replace the name on each existing row and drop any header-expression bridge:

     - id: mcp-linear
-      name: '@deepseek-ai/dsh-mcp-client'
+      name: 'dsh-mcp-client-plus'
       config:
         transport: streamable-http
         serverName: linear
         url: https://mcp.linear.app/mcp
-        headers:
-          Authorization: !!js >-
-            (function () { try { return 'Bearer ' + ...keychain read... } catch (e) { return ''; } })()
+        auth: oauth

Do not run both bridges for the same serverName: each holds its own namespace reservation, and the second registration fails on a duplicate public tool name.

Config reference

Fields common to both transports:

Field	Default	Meaning
serverName	required	Namespace for mcp__<serverName>__*; [A-Za-z0-9_-]{1,32}, unique among live instances
connectTimeoutMs	15000	Bound on one connection attempt
discoveryTimeoutMs	30000	Bound on one tools/list page
toolCallTimeoutMs	60000	Bound on one tool call
failOnStartupError	false	Reject plugin activation when the first attempt fails
reconnect.enabled	true	Reconnect after a lost connection
reconnect.initialDelayMs	500	First backoff delay; doubles per consecutive failure
reconnect.maxDelayMs	30000	Backoff ceiling, and the uptime that resets the outage budget
reconnect.maxAttempts	10	Per-outage ceiling. 0 retries indefinitely

transport: streamable-http only:

Field	Default	Meaning
url	required	MCP endpoint
auth	none	none, bearer, or oauth
headers	{}	Literal header values
headerEnv	{}	Header name → environment variable name
tokenEnv	—	Environment variable holding the bearer token
oauth.scopes	—	Scopes to request
oauth.callbackPath	/callback	Loopback redirect path
oauth.authorizationTimeoutMs	300000	How long to wait for the human
oauth.openBrowser	true	Launch the platform browser
oauth.storePath	$DSH_HOME/.dsh/mcp-client-plus-oauth.json	Credential store

For headless or remote hosts, set oauth.openBrowser: false — the authorization URL is always logged, so you can open it wherever your browser lives. The authorization server must accept a http://127.0.0.1:<port>/... loopback redirect, which the MCP specification requires for local clients.

The mcp_status tool

One mcp_status tool is registered per scope, reporting every server:

linear [connected] · 42 tools · auth=oauth · streamable-http
hex [failed] · 0 tools · auth=oauth · streamable-http · last error: giving up after 10 consecutive failed reconnect attempts …

Pass { "server": "hex" } to filter, or call it with no arguments to list all.

Compatibility

• DeepSeek Harness >=0.1.5-rc.1 <0.2.0. Tested on 0.1.5-rc.2.
• Node ^22.19.0 || >=24.0.0.
• Declares no npm dependencies or peerDependencies, matching the convention used by other dsh plugins: the harness's own @deepseek-ai/* packages and @modelcontextprotocol/sdk resolve from the profile's node_modules.
• Upstream master (0.1.6-alpha.2) moved to @modelcontextprotocol/client v2 and requires @deepseek-ai/dsh-mcp-resources; this fork is based on dsh-v0.1.5-rc.2. See PROVENANCE.md.

Relationship to dsh-mcp-manager

hyqhyq3/dsh-mcp-manager is a fuller-featured alternative and a good choice if you want a GUI: a Settings → MCP page, workspace-scoped servers, and an on-demand tool broker. This fork stays a drop-in replacement for the built-in bridge instead — same one-row-per-server composition model, same tool names, no client half and no GUI.

Development

npm run build      # tsc -> lib/  (lib/ is committed: dsh loads it directly)
npm test           # build first; runs node --test over tests/**/*.test.js

Because the plugin declares no dependencies, build and test resolve @deepseek-ai/* and @modelcontextprotocol/sdk from a harness install. Point node_modules at one before building:

ln -s "$(npm root -g)/@deepseek-ai/dsh/node_modules" node_modules

51 tests across three layers:

• Unit — the config and reconnect policy (including maxAttempts: 0), header and secret resolution, the OAuth provider's persistence and credential invalidation, and the loopback redirect listener driven over real HTTP.
• Transport end-to-end — a real MCP server over stdio through the transport factory: connect, tools/list, and tools/call. Plus an assertion that an unresponsive server fails inside connectTimeoutMs rather than the 60-second SDK default, and that bearer and headerEnv credentials reach the wire.
• Harness integration — apply() mounted on a real Cordis context against a real ctx.tools registry: tool registration and public naming, mcp_status reporting and rendering, disposal unregistering everything, duplicate serverName rejection, and failOnStartupError rejecting activation.

Known limitations

• Tools only. MCP resources and prompts are not bridged, same as upstream.
• One authorization per process for a new server. The redirect is received by a loopback listener owned by the plugin instance; if the host is headless, you complete the flow in whatever browser can reach the printed URL.
• OAuth tokens are stored in plaintext in a 0600 JSON file. Static bearer tokens are read from the environment and never persisted.
• connectTimeoutMs bounds initialize, not the whole TCP/TLS establishment; a hung DNS lookup may still take longer before the request timer applies.
• maxAttempts defaults to 10, unchanged from upstream. Set 0 for the retry-forever behaviour; the default was left alone deliberately so the fork does not silently change an existing deployment's resource profile.

License

MIT. Portions derived from DeepSeek Harness (packages/mcp/mcp-client, MIT) at dsh-v0.1.5-rc.2. See LICENSE and PROVENANCE.md.