Skip to main content
Glama

@nones/dsh-session-mcp

MCP (Model Context Protocol) server for DeepSeek Harness sessions — lets Claude Code, Claude Desktop, Codex, Cursor and any other MCP client work with the conversations running in your harness: list them, read them, prompt them, branch them, stop them, retitle them, switch their model.

Ships as a DeepSeek Harness plugin: installing the bundle starts a bearer-authenticated MCP endpoint together with the harness, publishes a copy-ready client config, and adds a Settings → MCP page with live status, the last few requests and every snippet you need. No sidecar process to babysit, no port to guess, no second writer on the session log.

┌──────────────────┐   Bearer token    ┌──────────────────────────────┐
│  Claude / Codex  │ ────────────────► │  http://127.0.0.1:7801/mcp   │
│  Cursor / other  │ ◄──────────────── │  inside the Harness process  │
└──────────────────┘   MCP over HTTP   └───────────────┬──────────────┘
                                                      │ in-process
                                                      ▼
                                           ┌─────────────────────┐
                                           │  sessionController  │
                                           │  list / page / …    │
                                           └─────────────────────┘

Why

DeepSeek Harness keeps its conversations behind a writer lock: a second dsh process that tries to resume a live session is rejected, and its own HTTP API authenticates with a launch token that lives only in memory. This plugin solves both by serving MCP inside the harness process, where the session controller is already available, and by giving clients a stable bearer token instead of a launch secret.

session_send therefore delivers into the conversation a human is looking at, not into a copy of it.

Related MCP server: MCP DSH Nexus

Install

dsh plugin --profile desktop add @nones/dsh-session-mcp

From a checkout or straight from git:

dsh plugin --profile desktop add /absolute/path/to/dsh-session-mcp
bun add github:ZeiZel/dsh-session-mcp

Restart the harness (or reload the profile) and the endpoint starts with it.

The Host half (endpoint, tools, config route) is live as soon as the bundle installs. The Client half — the Settings page — is composed into the browser module roster at boot, so it appears after the next harness start.

Tools

Eleven tools. Everything is scoped to this harness: no other instance is reachable.

Conversations

Tool

What it does

sessions_list

Conversations with id, title, working directory, run state and token usage. Start here.

session_read

Durable history — user, assistant and tool messages — pageable back with beforeSeq.

session_inspect

Vitals of one conversation: title, run state, tokens, context pressure, context breakdown, pending queue, selected model, goal.

session_search

Full-text search. Only works when the harness enables the session-query index; otherwise the host reports it is disabled.

Acting on a conversation

Tool

What it does

session_send

Deliver a user message into a live conversation (queue waits for the current turn, steer interrupts into it) and start a model turn.

session_create

Open a new blank conversation, optionally in a given cwd or agentPreset.

session_rename

Set the conversation title; returns the committed title and event position.

session_fork

Copy a prefix into a new conversation — branch off an alternative approach without touching the original. Omit atSeq to fork at the latest completed turn.

session_cancel

Stop the turn a conversation is running. Pending inbox work is kept, so a queued message is not lost.

Models

Tool

What it does

models_list

Every reachable provider/model route, the reasoning efforts each accepts, and the deployment default.

session_select_model

Pin one provider/model route (and optional reasoning effort) to a conversation.

A typical loop

sessions_list          → find the conversation
session_inspect        → is it running? how full is the context?
session_send           → queue the next instruction
session_read           → check what the agent answered

Branching instead of hijacking:

session_fork  { sessionId, atSeq }   → new conversation id
session_send  { sessionId: <new> }   → try the alternative there

Settings → DeepSeek MCP

The harness renders a dedicated settings page. It shows:

  • Status — listening, uptime, total requests served, and the last failure when one happened

  • Recent requests — the newest five tool calls: what ran, when, the conversation it addressed (title, with the id on hover), and whether it succeeded, with duration

  • Connection — the endpoint, an editable port, and the bearer token (masked until you reveal it) with a Rotate token action

  • three copy-ready blocks:

Block

For

JSON — mcpServers

Claude Desktop, Cursor, and any JSON-configured client

Codex — ~/.codex/config.toml

Codex CLI / IDE

Claude Code — CLI

One claude mcp add … command

Each block has its own Copy button; the endpoint and the token have one too. The page refreshes every 10 seconds while it is open.

Changing the port

Type a port and press Apply. The listener moves immediately, the state file and every snippet are rewritten, and the chosen port is remembered across restarts. If the port cannot be bound the listener stays where it was and the page says why.

The Settings page itself lives on the harness Web port, so moving the MCP endpoint never disconnects the page you are looking at — but every client config that names the old port stops working.

Rotating the token

Rotate token asks once for confirmation, then replaces the bearer. The running listener picks it up on the next request — no restart — and the old token stops working at the same moment. Update the clients you care about with the new value from the snippets.

Only the last five calls are kept — the plugin is not a log store, and schema-rejected calls (wrong arguments) never reach a tool, so they are not journalled. Conversation titles come from one session/list read per page load, so the journal itself stays cheap.

The same data is on disk at $DSH_HOME/state/dsh-session-mcp.json:

{
  "url": "http://127.0.0.1:7801/mcp",
  "token": "…",
  "client": {
    "mcpServers": {
      "dsh-sessions": {
        "type": "http",
        "url": "http://127.0.0.1:7801/mcp",
        "headers": { "Authorization": "Bearer …" }
      }
    }
  }
}

Connect a client

Claude Code

claude mcp add --transport http dsh-sessions http://127.0.0.1:7801/mcp \
  --header "Authorization: Bearer <token>"

Claude Desktop / Cursor / generic mcpServers

{
  "mcpServers": {
    "dsh-sessions": {
      "type": "http",
      "url": "http://127.0.0.1:7801/mcp",
      "headers": { "Authorization": "Bearer <token>" }
    }
  }
}

Codex (~/.codex/config.toml)

[mcp_servers.dsh-sessions]
url = "http://127.0.0.1:7801/mcp"

[mcp_servers.dsh-sessions.http_headers]
Authorization = "Bearer <token>"

Older clients that only speak the 2025 revisions still work: the endpoint serves the modern revision and falls back to stateless serving for 2025-era traffic.

Security

  • Binds loopback only (127.0.0.1) and rejects non-loopback Host headers.

  • Every request needs Authorization: Bearer <token>; the check is constant-time.

  • The token is 32 random bytes, generated once, stored 0600 at $DSH_HOME/state/dsh-session-mcp.json, and reused across restarts so pasted client configs keep working. Rotate it from Settings → DeepSeek MCP.

  • The Settings page reads its data from /api/dsh-session-mcp/config over the authenticated browser channel, so the token never enters the served HTML.

  • Rotating from the page (or deleting the state file and restarting) invalidates every client config that still carries the old token.

  • Never expose this endpoint through a proxy or a tunnel: the bearer is the only thing between a client and every conversation you have.

Configuration

The plugin row accepts two options (cordis.patch.yml):

Option

Default

Meaning

port

7801

Initial loopback port. A port chosen in Settings is stored in the state file and wins over this value on the next start; if the port is taken, an ephemeral one is used and the state file is republished with the real URL.

host

127.0.0.1

Bind address.

How it works

Written in TypeScript, compiled to dist/ (committed, so installs need no build step).

Source

Role

src/index.ts

Cordis plugin: reads/creates the bearer, starts the listener, publishes the state file, serves the Settings routes (read config, move port, rotate token), closes the listener on unload

src/server.ts

node:http listener with the bearer gate in front of the official SDK's createMcpHandler + toNodeHandler

src/tools.ts

The eleven tools, backed directly by ctx.sessionController

src/log.ts

Bounded journal of the last five calls

src/config.ts

Token persistence, constant-time bearer comparison, client snippets

src/client.ts

The Settings → MCP page (classic script for window.__ModuleLoader__)

src/types.ts

The narrow structural slice of Harness types this package needs

Releases

Publishing is automatic: pushing a v* tag makes GitHub Actions build the package, publish it to npm with a signed provenance statement, and cut a GitHub release.

npm version patch --no-git-tag-version
git commit -am "chore(release): 1.3.1"
git tag v1.3.1
git push origin master --tags

The workflow requires one repository secret, NPM_TOKEN (npm automation token).

Contributing

See CONTRIBUTING.md.

License

MIT © ZeiZel

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables permission-scoped MCP clients to interact with DeepSeek Harness Desktop over a local loopback HTTP bridge, including checking status, listing models/workspaces/sessions, reading bounded session history, and creating, sending, waiting for, or canceling chats. Access is restricted per bearer token and only exposes the tools and sessions granted to that token.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables any MCP-capable client (Claude Code, Cursor, VS Code, and others) to deliver messages into a local DeepSeek Harness over stdio or Streamable HTTP. It also exposes a pull-based task queue so producers can publish work that clients claim, complete, or list.
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables any MCP client to hand self-contained coding tasks to a local DeepSeek Harness instance, which executes them by reading and editing files and running commands within whitelisted directories. Exposes a health check and a blocking task-runner over stdio or authenticated HTTP, returning stdout, stderr, exit code, and duration.
      MIT