dsh-chatgpt-bridge

An MCP bridge that lets ChatGPT Web create, view, continue and supervise DeepSeek Harness (DSH) agent sessions through the official Model Context Protocol. v0.3.0 — Goal Control Plane. The bridge only connects — DSH keeps its own session log, agent loop, tools, skills, subagents, workflows, approvals, sandbox and workspace security model. It is a standalone DSH plugin: zero DSH core modifications.

Self-hosted / dogfooding development: implemented against the installed DeepSeek Harness source (0.1.0-rc.6) and verified end-to-end against a live local DSH runtime with the official MCP SDK client.

---

Quick Start

This gets a new user from zero to a verified ChatGPT ↔ DSH connection. Deep architecture and configuration details follow below — you do not need them to install and verify.

Requirements

• Node.js >= 22 installed and on your PATH.
• A working DeepSeek Harness (DSH) installation — dsh on your PATH (or use pnpm dlx @deepseek-ai/dsh@0.1.0-rc.6 in place of dsh in every command below).
• A web profile is recommended. The Web UI and the Bridge should run in the same web profile/runtime so that ChatGPT-created sessions appear live in DSH Web.
• ChatGPT-side MCP and write-action availability depends on your current plan/workspace. Check OpenAI's current official documentation before setup.
• This plugin includes write/action tools (dsh_send_message, dsh_start_goal, dsh_approve, ...), not just read-only MCP. It drives a real DSH agent that can modify files inside registered workspaces under DSH's approval/sandbox policy. Treat it accordingly.

1. Install

Recommended — install the plugin into the web profile (from the published npm package):

dsh plugin --profile web add dsh-chatgpt-bridge

npm install dsh-chatgpt-bridge alone is not enough: the plugin must be added to a DSH profile bundle, which dsh plugin ... add does for you. See Detailed install for source, headless, and manual variants.

2. Start one shared DSH runtime

dsh web

Run the DSH Web UI and the Bridge in the same web profile/runtime. ChatGPT-created sessions are native DSH sessions; they only stream live in DSH Web when both share one runtime.

| Endpoint | URL | | --- | --- | | DSH Web | http://127.0.0.1:3080 | | Bridge MCP | http://127.0.0.1:3456/mcp |

3. Read the authentication token

On first boot the bridge generates a token and persists it to $DSH_HOME/chatgpt-bridge.token. Read it with:

Windows (PowerShell):

Get-Content "$HOME\.dsh\chatgpt-bridge.token"

macOS / Linux:

cat ~/.dsh/chatgpt-bridge.token

Never commit this token to GitHub or paste it into a public chat. It authorizes MCP access to your DSH runtime. Alternatively, set DSH_CHATGPT_BRIDGE_TOKEN yourself and the bridge uses it instead of the generated file.

4. Connect ChatGPT

ChatGPT Web cannot open a plain localhost MCP endpoint. A URL like http://127.0.0.1:3456/mcp exists only on your machine; ChatGPT Web is a remote MCP client and cannot reach it directly.

• If the Bridge runs on your machine, connect ChatGPT through the Secure MCP Tunnel / secure tunneling mechanism that OpenAI currently supports for MCP/custom apps. The tunnel forwards ChatGPT's requests to the loopback endpoint.
• Use the token from step 3 as the MCP Authorization Bearer token for the connector/tunnel.
• The Bridge keeps its localhost-first design: it binds 127.0.0.1, never exposes a public interface, and never self-hosts a tunnel.
• The stdio transport is not the ChatGPT Web quick path — ChatGPT Web does not launch local processes. See Advanced / other MCP clients for stdio and non-ChatGPT MCP clients.

5. Scan / refresh tools

After the MCP connection is established, scan / refresh the MCP tools in ChatGPT. v0.3.0 exposes 15 tools, and dsh_update_goal must be present (it is the 15th). If the tool list looks stale, refresh/rescan the connector (see Tool count is stale).

6. First verification

Give ChatGPT this read-only acceptance prompt:

请使用已连接的 DSH App，只做只读检查：
1. 调用 dsh_health
2. 调用 dsh_list_workspaces
3. 不修改任何文件
4. 返回 bridge version、health 和 workspace 名称

Expected:

health = ok
bridge version = 0.3.0

Then a minimal Goal Supervision example (still read-only):

使用 dsh_start_goal 创建一个只读检查目标（workspace 用 dsh_list_workspaces
查到的名称），goal 描述为“只读检查项目”，plan 为列出项目结构并总结
README，constraints 使用 {"read_only": true}。然后反复调用 dsh_wait_goal
直到 terminal，最后只汇报 health、goal revision 和总结，不修改任何文件。

---

Troubleshooting

ChatGPT cannot connect

http://127.0.0.1:3456/mcp is a loopback address on your machine — ChatGPT Web cannot reach it as a remote MCP server. Check the Secure MCP Tunnel / currently supported secure connection method for MCP/custom apps: the tunnel must forward to the loopback endpoint with the bearer token.

401 Unauthorized

• Read the token: Get-Content "$HOME\.dsh\chatgpt-bridge.token" (PowerShell) or cat ~/.dsh/chatgpt-bridge.token (macOS/Linux).
• The connector must send it as the Authorization: Bearer <token> header.
• The token belongs to the runtime that generated it. A different $DSH_HOME, a regenerated token, or a mismatched DSH_CHATGPT_BRIDGE_TOKEN all cause 401 — make sure the token matches the currently running runtime.

dsh_health works but no workspace appears

dsh_list_workspaces only lists workspaces already registered in DSH. The bridge never auto-registers arbitrary paths; dsh_create_session with an unregistered path fails with WORKSPACE_NOT_FOUND on purpose. Register the workspace in DSH (Web profile workspace settings / DSH configuration) first.

Session exists but does not appear live in DSH Web

The Bridge and DSH Web must run in the same web profile/runtime. Do not run a separate chatgpt-bridge runtime and a separate web runtime and expect live parity — sessions persist and can be resumed, but they will not stream in real time.

Tool count is stale / dsh_update_goal missing after upgrade

Re-scan / refresh the MCP tools on the ChatGPT side after upgrading the plugin and restarting the profile. v0.3.0 exposes 15 tools; dsh_update_goal is the 15th.

Port 3456 already in use

Identify the process first — never auto-kill an unknown process. On Windows (PowerShell):

Get-NetTCPConnection -LocalPort 3456 | Select-Object LocalAddress, LocalPort, OwningProcess
Get-Process -Id <OwningProcess> | Select-Object Id, ProcessName, Path

On macOS/Linux:

lsof -iTCP:3456 -sTCP:LISTEN     # or: ss -ltnp 'sport = :3456'

If it is an old dsh/bridge process, stop it cleanly. Otherwise change the bridge port in the profile config (see DSH configuration) or free the port.

Bridge error codes

| Symptom | Cause / fix | | --- | --- | | WORKSPACE_NOT_FOUND | The workspace is not registered in DSH; dsh_list_workspaces shows what is allowed. | | SESSION_NOT_FOUND | Unknown session id (never created, or persistence not mounted). | | SESSION_NOT_LIVE on cancel | The session is not loaded in this process; only live sessions can be cancelled. | | APPROVAL_NOT_FOUND / QUESTION_NOT_FOUND | The decision was already taken or the bridge restarted (parked decisions are in-memory). | | question provider slot taken (log) | A web UI is attached and owns user questions; answer them in the UI. | | Cold sessions show no title in dsh_list_sessions | Cold titles come from the projection cache; concurrent DSH profiles sharing the cache can clobber rows. Single-profile deployments get titles. |

---

60-second smoke test

After completing Quick Start steps 1–3:

1. dsh web — one shared runtime.
2. Establish the MCP tunnel to http://127.0.0.1:3456/mcp.
3. In ChatGPT: Scan Tools.
4. Ask ChatGPT to call dsh_health.
5. Confirm:
   • health = ok
   • bridge version = 0.3.0
   • tool count = 15
   • dsh_update_goal exists in the tool list
6. Optionally call dsh_list_workspaces to confirm your workspace is visible.

---

Architecture

ChatGPT Web
      |
      | MCP (Streamable HTTP / stdio)
      v
dsh-chatgpt-bridge        <- a DSH (Cordis) plugin row
      |
      v
DeepSeek Harness          <- sessions, agents, tools, approvals, sandbox, workspace
      |
 +----+--------------+
 |    |              |
Session   Agent     Workflow
 |    |              |
 +----+------+-------+
             v
       Local Workspace

The bridge uses DSH's public plugin seams — it never re-implements DSH:

| DSH capability seam | Usage in the bridge | | --- | --- | | ctx.agents (AgentRegistry) | create() / resume() / get() — live agent lookup, session creation, and resume of persisted sessions after restarts | | ctx.sessions (SessionStore) | live session listing, flush() durability | | ctx.sessionPersistence | list() / inspect() — the DSH session log is the authority for session identity across ChatGPT conversations | | ctx.sessionTitle | title read/write (plus the session/title log fold) | | ctx.workspaceRegistry | list + resolve — only registered workspaces can host sessions | | ctx.approval (approval/request waterfall) | the bridge is an answerer: approvals park as waiting_for_approval and are decided one-by-one | | ctx.userQuestions (registerProvider) | the bridge is the question provider: questions park as waiting_for_user | | ctx.agentDefaultModel | default provider/model selection for created sessions | | ctx.agentPresets (mount) | same per-session preset composition the Web UI uses, when a roster exists | | installModelSelection (dsh-agent) | per-agent model selection with log-derived fallback on resume | | createUserMessage + agent.followup() | the canonical way to continue a session's durable log |

MCP facts

| Item | Value | | --- | --- | | Transport | Streamable HTTP (default, http://127.0.0.1:3456/mcp) or stdio | | Protocol version | negotiated by @modelcontextprotocol/sdk 1.30.0 (official MCP SDK) | | Authentication | Bearer token (default): config token → DSH_CHATGPT_BRIDGE_TOKEN env → generated token persisted to $DSH_HOME/chatgpt-bridge.token | | Local endpoint | http://127.0.0.1:3456/mcp (loopback only by default) | | ChatGPT connection | any official MCP client: a local connector at the endpoint with the token, or a remote connector tunneled to the loopback endpoint (e.g. OpenAI's supported Secure MCP Tunnel). The bridge never exposes anything public by itself. |

---

Detailed install

The plugin is a standard DSH profile bundle. It currently targets DSH 0.1.0-rc.6.

Recommended: one DSH runtime for both Web :3080 and the MCP bridge :3456. ChatGPT-created sessions are native DSH sessions. The Web UI only sees them live if it shares ctx.agents / ctx.sessions with the bridge. Do not run a headless chatgpt-bridge profile and a separate web profile at the same time — that is two runtimes and live Web parity will fail.

Install into the Web profile (recommended)

The Quick Start uses dsh plugin --profile web add dsh-chatgpt-bridge. If dsh is not on your PATH, the equivalent is:

pnpm dlx @deepseek-ai/dsh@0.1.0-rc.6 plugin --profile web add dsh-chatgpt-bridge
# published: ... add dsh-chatgpt-bridge@0.3.0

# boot ONE process — Web :3080 and MCP :3456
pnpm dlx @deepseek-ai/dsh@0.1.0-rc.6 --profile web

dsh_health.capabilities.webSurface is true when the Web gateway is in this process.

Headless-only (optional)

A dedicated chatgpt-bridge profile (no Web) still works. Sessions persist and can be resumed later, but DSH Web :3080 will not stream them in real tim