Introduction

DeepSeek Harness (DSH) provides localized, high-performance AI workflow execution capabilities, but in real-world development, interacting with it directly via CLI is often not flexible enough. When developers use standard MCP (Model Context Protocol) clients such as Codex, Claude Code, and Cursor, they need a way to connect Harness’s capabilities to these agents.

harness-relay-mcp is designed for exactly this purpose. It serves as the MCP control plane for DeepSeek Harness, allowing external MCP agents to delegate tasks, monitor progress, and retrieve persistent results, rather than merely wrapping Harness as an ordinary model call.

What This Is

harness-relay-mcp is a standalone open-source project (Maintainer: tonytanglab, License: MIT). It is not a wrapper around DeepSeek models; instead, it is a bridge connecting external MCP agents to local DeepSeek Harness instances.

Its core positioning is as a control plane, not a model layer. It does not perform model inference; instead, it takes over Harness session management, permission control, tool scheduling, and event persistence, and exposes these capabilities to external agents through the MCP protocol.

Core Features

The plugin provides the following capabilities:

  1. Native sessions and persistent events: Uses Harness’s native session model and event system, rather than parsing CLI output, to ensure accurate state.
  2. Complete asynchronous lifecycle: Supports starting tasks, querying status, waiting, steering, replying, canceling, and reopening.
  3. Rich configuration options: Before submitting a task, you can select Provider, Model, Reasoning Effort, Agent Preset, and native permissions.
  4. Tiered permission support: Directly supports Harness’s three native permission levels: read-only, workspace write, and dangerous full access.
  5. Multimodal support: Supports ordered text and inline image prompts, with boundary validation for Base64 encoding.
  6. High availability: Maintains persistent run identity and can restore context after the MCP server restarts.
  7. Visualization and validation: Provides stable Harness Web session links, and the bundled Skill includes an explicit page validation mechanism.
  8. Broad compatibility: Compatible with standard MCP clients such as Codex, Claude Code, OpenCode, and Cursor.

Installation and Enabling

Installation via the official DeepSeek Harness profile is recommended.

  1. Install the plugin
    Use the profile command to add the plugin to Harness:
    dsh plugin --profile web add harness-relay-mcp
  1. Verify the configuration
    Check whether the configuration includes the plugin information:
    dsh --profile web --dump-config

Ensure the output includes `id: harness-relay-mcp` and `name: 'harness-relay-mcp'`.
  1. Start Harness
    Start the configured profile:
    dsh --profile web
  1. Uninstall (if needed)
    Uninstalling the plugin does not cancel submitted workflows:
    dsh plugin --profile web remove harness-relay-mcp

Typical Usage

MCP Agent Interaction Flow

External MCP agents can control Harness through the following flow:

  1. Start a task: Call start_run, and select Provider, Model, Reasoning, Preset, and Permission in the parameters.
  2. Monitor and control: Check the status using status_run, or use wait_run to wait for completion. During this time, you can use steer_run to steer the task.
  3. Retrieve results: After the task completes, retrieve the persistent results and the native Harness Web session URL.

Using the Codex Plugin

If you use Codex as an MCP client, you need to install the corresponding plugin layer (Note: the Codex plugin is an external invocation layer and does not replace the Harness bundle):

  1. Register the Marketplace:
    codex plugin marketplace add tonytanglab/deepseek-harness-relay-mcp
  1. Add the plugin:
    codex plugin add deepseek-harness-relay@harness-relay
  1. List installed plugins:
    codex plugin list

Use Cases and Cautions

Use Cases

  • Long-running tasks: Tasks that require complex tool calls inside Harness or that run for an extended period.
  • Permission management: Scenarios that require precise control over agent read/write permissions to the workspace (read-only, write, full access).
  • Persistent monitoring: Scenarios that require restoring task state across sessions or restarts.
  • Web inspection: Scenarios that require manual inspection or debugging through the Harness Web interface.

Important Notes

  • Version requirements:
    • Internal mode: Requires the DeepSeek Harness version to be between >=0.1.3-alpha.2 <0.2.0, and uses the web profile with bind address 127.0.0.1.
    • Standalone compatibility mode: Requires a local DeepSeek Harness Web Host to be running (default address: http://127.0.0.1:3080/).
  • Workspace registration: The target workspace must already be registered with Harness or be located under an explicitly configured allowed root directory.
  • Avoid loops: Do not configure Relay simultaneously as an MCP client in Harness, otherwise it will cause infinite recursion of Harness -> Relay -> Harness.
  • Uninstall impact: Removing Relay infrastructure does not cancel submitted Harness workflows; they must be handled manually in Harness.
  • Historical compatibility: Relay 0.2.6 and earlier versions target the removed rc.7 ApiProxy surface and are incompatible with the current Harness line.
  • Developer preview: DeepSeek Harness is currently in developer preview. It is recommended to consult the official repository again before use for the latest updates.

Summary

harness-relay-mcp addresses the pain points of integrating DeepSeek Harness with external MCP agents, providing full control plane capabilities. It allows developers to enjoy Harness’s powerful workflow execution, permission management, and persistent monitoring capabilities within familiar agent interfaces.

Plugin directory: DeepSeek Harness Relay MCP

Source repository: tonytanglab/deepseek-harness-relay-mcp