DeepBridge

A local MCP/A2A bridge that enables Codex to delegate tasks to DeepSeek Harness with reusable conversation context.

Overview

Codex can delegate a focused engineering or technical task to DeepSeek Harness and receive the task status and final response through an MCP tool. The Bridge translates between MCP, A2A, and ACP while leaving the Harness itself unchanged. A local read-only dashboard shows tasks handled by the running Bridge.

Related MCP server: dsh-crew

Architecture

Codex Host
    ↓ MCP (stdio)
A2A Bridge
    ↓ ACP
DeepSeek Harness

context_id and task_id have different roles:

• context_id identifies a conversation context. Reusing it continues the same in-memory DeepSeek Harness ACP session. Different context IDs remain isolated.

• task_id identifies one A2A task. Each delegation gets its own task ID, even when several tasks use the same context.

Context sessions and task records belong to one Bridge process. They are not restored after a Bridge restart.

Features

• MCP task delegation to DeepSeek Harness through A2A and ACP.

• Multi-turn continuation using a reusable context_id.

• Separate context sessions for different contexts.

• Read-only local dashboard with task input, status, progress timeline, and result.

• Bounded startup, session, prompt, cancellation, and cleanup timeouts.

• A2A cancellation forwarding and Bridge permission-request handling.

• Configurable retention limits for terminal A2A tasks.

Requirements

• Node.js 22.12 or newer.

• Codex with support for local stdio MCP servers.

• DeepSeek Harness installed and configured, with the acp profile available.

The Bridge has been tested with @deepseek-ai/dsh@0.1.5-rc.3. This is a prerelease; compatibility depends on the external DeepSeek Harness release and is not guaranteed across versions.

Install DeepSeek Harness separately and configure its provider/model before using the Bridge. The Harness CLI can be installed with:

npm install --global @deepseek-ai/dsh@0.1.5-rc.3

Installation

git clone https://github.com/ELYSIA1066/DeepBridge.git
cd DeepBridge
npm install

Configure a DeepSeek provider/model in DeepSeek Harness. If needed, start its setup UI with dsh web, finish configuration, and stop that process. The Bridge starts the ACP profile itself when it needs to run a task.

Configuration

The Bridge reads configuration from its environment. Invalid or missing timeout values use the documented defaults; A2A_PORT and CONTEXT_IDLE_TTL_MS must be positive valid integers.

The task count and retention limits apply to terminal tasks. A task that remains active is not removed by that retention policy.

Codex MCP Setup

Register the MCP server with Codex. Replace <project-root> with the absolute path to the cloned repository; the command uses the locally installed tsx development dependency:

codex mcp add deepseek-agent --env A2A_BRIDGE_URL=http://127.0.0.1:41241 -- node "<project-root>/node_modules/tsx/dist/cli.mjs" "<project-root>/app/mcp.ts"

The MCP façade starts a missing Bridge only when A2A_BRIDGE_URL points to a local loopback address. It reuses a healthy existing Bridge. Set DSH_COMMAND or DSH_HOME in the MCP environment when your DSH installation needs them; the Bridge process receives the MCP environment.

Usage

Use the delegate_to_deepseek MCP tool with a required task description and an optional context_id:

{
  "task": "Review the error handling in the current project.",
  "context_id": "project-review"
}

Reuse the returned context_id to continue that DeepSeek Harness conversation. Omit it to let the MCP façade create a new context. Only one task may be active for a context at a time. Results include the task status and, when available, task_id and a direct dashboard link.

Dashboard

The read-only dashboard is available at http://127.0.0.1:41241/ui/ while the Bridge is running. It lists tasks handled by that Bridge, groups them by A2A context, and displays task input, status, progress events, and the final result. It refreshes every three seconds while visible. Older retained tasks can be loaded on demand.

The dashboard shows ACP assistant text and tool titles/statuses reported for each task. It does not show model thoughts, tool arguments, or tool results. Progress consists of committed semantic updates, not token-by-token output. Task records and progress are in memory and are lost when the Bridge restarts or retention removes a terminal task.

Permission Model

The Bridge launches DSH with DSH_PERMISSION_MODE=read-only and rejects ACP permission requests according to its Bridge policy. An ACP permission request rejected by the Bridge maps to A2A REJECTED.

A tool-level operation that DSH denies under its own policy may instead be described by the assistant as a normal response; if the ACP prompt completes normally, the A2A task can be COMPLETED. COMPLETED means the prompt completed, not that every requested side effect occurred.

Security

• The Bridge listens on 127.0.0.1 by default and has no authentication. Do not expose the A2A server or dashboard to a LAN or the public internet without adding an authentication and access-control layer.

• The DSH child process inherits the Bridge process environment. Do not run the Bridge with unrelated secrets in its environment that you do not want Harness tools to access.

• DSH's read-only permission mode is not an operating-system sandbox or a security boundary. Use a least-privilege, appropriately isolated environment, especially for untrusted tasks.

• See SECURITY.md for reporting and handling security concerns.

Known Limitations

• Task records, progress, and context mappings are in-memory only. Restarting the Bridge clears them; session recovery and persistence are not implemented.

• There is no global scheduler, queue, or global concurrency limit. Only one active task per context is allowed.

• Idle context cleanup is checked when a later task arrives, rather than by a dedicated timer.

• DSH compatibility depends on the separately installed upstream Harness version and ACP profile.

• Read-only permission mode is not an operating-system sandbox.

• Text input and Markdown text output are supported; progress is available in the local dashboard, while A2A returns task lifecycle updates and the final artifact.

Testing

npm test
npm run typecheck

The automated tests use mock ACP/DSH boundaries. They do not call DeepSeek or consume API usage.

License

MIT License. See LICENSE.