Harness Relay MCP

English | 简体中文

Delegate and monitor DeepSeek Harness work from any MCP agent.

Delegate long-running work to DeepSeek Harness from any MCP-capable agent—and monitor it to completion.

Harness Relay MCP connects MCP clients to the native DeepSeek Harness session and event model. Its recommended form is a tree-external Harness bundle; it does not wrap the CLI, patch Harness source, or own the Harness process.

MCP agent
   │
   ├─ start_run ── provider / model / reasoning / preset / permission
   │
   ├─ status_run / wait_run / steer_run / cancel_run
   │
   └─ durable result + native Harness Web session URL

Positioning: Harness control plane, not a model wrapper

Harness Relay MCP is an independent third-party project. It is not developed, endorsed, or supported by DeepSeek AI.

> This is not a DeepSeek model wrapper. It is the MCP control plane for DeepSeek Harness.

Do not confuse three different integration directions:

• The official DeepSeek Harness repository currently documents mcp-client, which lets Harness consume external MCP servers. It is the opposite direction from exposing Harness as an MCP-controlled worker.
• Direct DeepSeek MCP servers call a model API and return model output. They do not enter the native Harness session, plugin, workspace, permission, or event lifecycle.
• Harness Relay MCP attaches to an existing official Harness Host and exposes that Host's native capabilities to external MCP agents.

As of 2026-08-20, the official dsh launcher source provides profile boot and plugin management but no documented outbound dsh mcp server command. DeepSeek Harness is a developer preview, so re-check the official repository before relying on this comparison.

Comparison last verified: 2026-08-20.

Choose the right tool

• Use a direct DeepSeek MCP server for bounded classification, extraction, summarization, or a quick second opinion where plain model output is enough.
• Use Harness Relay MCP when the task must run inside DeepSeek Harness and needs its registered workspaces, tools, plugins, provider catalog, native permissions, persistent sessions, long-running monitoring, recovery, or Web inspection.
• Do not install Relay only to replace one ordinary chat-completions request; the additional Host, state, authentication, and proxy layers would add complexity without providing useful control-plane value.

Highlights

• Native Harness sessions and durable events instead of CLI output parsing.
• Complete asynchronous lifecycle: start, status, wait, steer, reply, cancel, and reopen.
• Provider, model, reasoning effort, agent preset, and native permission selection before the first task prompt.
• Direct support for read-only, workspace-write, and danger-full-access Harness permissions.
• Ordered text and inline image prompts with bounded base64 validation.
• Persistent run identities and recovery after the MCP server restarts.
• Stable Harness Web session links, with explicit visible-page verification in the bundled Skill.
• Compatible with Codex, Claude Code, OpenCode, Cursor, and other standards-compliant MCP clients.
• The internal bundle uses the official InProcess ApiProxy and native permission service; external agents connect through authenticated HTTP or the stateless stdio proxy.
• The standalone dsh-relay mode remains available for older Harness versions and explicit rollback.

Requirements

• Node.js ^22.19 or >=24.
• Internal mode requires the DeepSeek Harness 0.1.0-rc.7 compatible line, the web profile, and a 127.0.0.1 bind.
• Standalone compatibility mode requires a running DeepSeek Harness Web Host on loopback HTTP.
• The target workspace must already be registered by Harness or be inside an explicitly configured allowed root.

The default Host is:

http://127.0.0.1:3080/

Installation

Install as a Harness bundle (recommended)

Install the published package from npm with the official profile command, inspect the composed configuration, and then start the profile:

dsh plugin --profile web add harness-relay-mcp
dsh --profile web --dump-config
dsh --profile web

For an offline or pinned-file installation, download the release tarball and replace harness-relay-mcp in the first command with its local .tgz path.

The dump must contain id: harness-relay-mcp and name: 'harness-relay-mcp', so the Harness inventory shows the slash-free name harness-relay-mcp. If dsh web is already running, restart that Host after an install or upgrade so it loads the new bundle. Once started, the bundle continues to publish its non-secret descriptor at the backward-compatible path $DSH_HOME/plugins/dsh-relay/web/relay-endpoint.json; its Bearer token lives separately in the Host-specific state directory.

Uninstalling infrastructure does not cancel submitted Harness work:

dsh plugin --profile web remove harness-relay-mcp

Do not configure Relay into the same Harness MCP client, which would create a Harness → Relay → Harness recursion.

Install the Codex plugin

The Codex plugin is an external caller layer; it does not replace the Harness bundle above. First confirm that dsh --profile web has loaded harness-relay-mcp, then install the Codex plugin from this repository's marketplace:

codex plugin marketplace add tonytanglab/deepseek-harness-relay-mcp
codex plugin add deepseek-harness-relay@harness-relay
codex plugin list

The first command registers this project's GitHub marketplace. The second fetches the same-version plugin package from npm and loads its .mcp.json plus the delegate-to-deepseek-harness Skill in Codex. The Codex layer starts only the stateless dist/dsh-relay-proxy.mjs, which discovers and connects to the running Harness bundle through its endpoint descriptor. It does not modify DeepSeek Harness source, the internal bundle configuration of the web profile, or cordis.patch.yml.

Restart Codex after installation and start a new Codex task so the new task loads the MCP server and Skill. In that task, ask:

Call Harness Relay doctor and list_workspaces in read-only mode to verify the Harness Host, Relay endpoint, and workspace registry.

To refresh the repository marketplace and reinstall the Codex plugin:

codex plugin marketplace upgrade harness-relay
codex plugin add deepseek-harness-relay@harness-relay

Restart Codex and create another new task after the upgrade. Never configure Relay as an MCP client of the same Harness instance. Codex connects to the Relay proxy, while Harness continues to manage its internal bundle through dsh plugin --profile web add harness-relay-mcp. See the OpenAI plugin packaging documentation for the official marketplace format and commands.

#### Ask AI to analyze and assist with installation

Before the plugin is installed, users can give the following prompt to Codex with terminal access. The AI should inspect the environment read-only, explain the proposed changes, and obtain confirmation before installing. It must not modify the DeepSeek Harness product source or configure Relay back into the Harness MCP client:

Read the Installation section at https://github.com/tonytanglab/deepseek-harness-relay-mcp/blob/main/README.md and help me install Harness Relay MCP.
First inspect the operating system, Node.js version, dsh, Codex CLI, Harness web profile, and 127.0.0.1:3080 without modifying files.
Report the checks, missing dependencies, exact commands, and impact. Wait for my confirmation before making changes.
On the Harness side, install the internal bundle only with dsh plugin --profile web add harness-relay-mcp. Do not modify DeepSeek Harness source and do not add Relay as a Harness MCP client.
On the Codex side, add the tonytanglab/deepseek-harness-relay-mcp repository marketplace and install deepseek-harness-relay@harness-relay.
After installation, verify dsh --profile web --dump-config and codex plugin list, then remind me to restart Codex, create a new task, and run doctor and list_workspaces.
If any command fails, stop and report the original error. Do not broaden permissions or delete existing configuration.

Local development

pnpm install
pnpm run build

After the internal bundle starts, point MCP clients at the universal stdio proxy:

{
  "mcpServers": {
    "harness-relay-mcp": {
      "command": "node",
      "args": ["C:/Users/you/plugins/deepseek-harness-relay-mcp/dist/dsh-relay-proxy.mjs"],
      "env": {
        "DSH_RELAY_CLIENT_PRINCIPAL_ID": "cursor:project"
      }
    }
  }
}

The proxy defaults to $DSH_HOME/plugins/dsh-relay/web/relay-endpoint.json; when DSH_HOME is unset it consistently falls back to .dsh under the user home, and a blank DSH_PROFILE falls back to web. Set DSH_RELAY_ENDPOINT_DESCRIPTOR when using a custom state directory. Client configuration never stores the token. The harness-relay-mcp package root is the Harness bundle and ships harness-relay-mcp plus harness-relay-mcp-proxy; the old dsh-relay commands remain compatibility aliases.

Starting with 0.2.3, the internal bundle atomically publishes a credential-free relay-status.json beside the endpoint descriptor. The stdio proxy starts its local MCP surface first. If the endpoint is missing, startup failed, owner epochs disagree, the token is unreadable, or POST returns 401/404/405/503, tools/list still exposes the local doctor and other calls return RELAY_ROUTE_UNAVAILABLE. The same proxy reconnects after Host recovery and emits tools/list_changed; clients that do not process that notification must call tools/list again.

Quick start

First discover the native Harness workspace registry instead of treating the Host process directory as an authorization list:

{
  "tool": "list_workspaces",
  "arguments": {}
}

Then discover the Host capabilities instead of guessing route names:

{
  "tool": "list_capabilities",
  "arguments": {}
}

Then dispatch a read-only Kimi K3/MAX review:

{
  "tool": "start_review",
  "arguments": {
    "workspace": "D:/work/project",
    "task": "Review this workspace and return reproducible findings only.",
    "provider": "kimi-coding",
    "model": "k3",
    "reasoningEffort": "max",
    "agentPreset": "standard",
    "idempotencyKey": "review-2026-08-19-001"
  }
}

Store the returned runId, sessionId, and webUrl. Poll without blocking indefinitely:

{
  "tool": "wait_run",
  "arguments": {
    "runId": "<run-id>",
    "timeoutMs": 30000
  }
}

For an active correction, use steer_run. After a run reaches a terminal state, use reply_run to continue the same native Harness session.

Omitting both sessionId and sessionMode creates a fresh session inside the selected Harness workspace. To continue an existing project conversation, call list_workspace_sessions first and pass its idle sessionId, or pass sessionMode: "latest-idle" to reuse the newest nonblank, idle, unarchived session. An explicit sessionId cannot be combined with sessionMode.

Run lifecycle

start_run
   │
   ├─ reserve the session
   ├─ select model and native permission preset
   ├─ persist runId + prompt rpcId
   ├─ submit session.prompt
   └─ reconcile durable history

running ── status/wait/steer/cancel ──> succeeded | incomplete | failed | cancelled | needs_attention
   │
   └─ terminal ── reply_run ──> a new run in the same session

promptAdmission reports the prompt admission state:

start_run parameters

Image prompts

Use canonical base64 without a data: URL prefix:

{
  "workspace": "D:/work/project",
  "content": [
    { "type": "text", "text": "Review this screenshot." },
    {
      "type": "image",
      "mediaType": "image/png",
      "data": "<canonical-base64>",
      "name": "screen.png"
    }
  ]
}

Supported media types are PNG, JPEG, WebP, and GIF. Image bytes are forwarded to Harness but are not retained in Relay run snapshots or state files.

Native permission presets

DSH Relay invokes the native Harness /permission command through commands/execute and verifies the resulting session projection before submitting the first task prompt. A textual instruction is never treated as a permission boundary.

MCP tools

Client setup and monitoring projection

setup_plan supports Codex, Claude Code, Cursor, and the explicitly versioned OpenCode V2 layout. It accepts already-resolved absolute Node and Relay entry paths and returns only a structured minimal patch; it never edits a client configuration. The launcher platform must match the configuration platform, and package-manager shims such as pnpm.exe or pnpm.cmd are rejected as Node runtimes.

setup_doctor is also side-effect free. Filesystem, Broker, Host, workspace, model, and permission facts must be supplied by an authorized caller; omitted probes are reported as skipped instead of being guessed.

get_run_summary consumes the authoritative Relay run snapshot and exposes the versioned monitoring projection. read_notifications replays notifications retained by the current MCP server process and returns explicit cursor-gap metadata. Native run-notification transport is not enabled yet, so clients must treat an empty buffer as normal and fall back to get_run_summary, wait_run, or get_run polling.

Persistence and recovery

The default state file is:

%LOCALAPPDATA%/dsh-relay/state.json

State is schema-validated, locked across processes with owner-verified leases, and written through atomic replacement with restrictive file permissions where supported. Stale writers cannot regress stopped services, terminal runs, attention states, operations, or permission leases. Invalid files are quarantined rather than overwritten. By default, prompt text and image bytes are not persisted. After a Relay restart, run and operation identities are restored and reconciled with native Harness history. Assistant text from the reconciled turn is retained in event order instead of returning only the final assistant message. A run that produces no durable progress for the configured interval enters needs_attention with attentionReason: run_stalled; later progress automatically returns it to running.

Multiple local MCP server processes may share one state file; writes are serialized and merged by stable identifiers. An a

…