codex-dsh-mcp
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| DSH_CODEX_DSH_HOME | No | DSH data directory. | |
| DSH_CODEX_LOG_FILE | No | Path to the diagnostic log file. | |
| DSH_CODEX_LOG_LEVEL | No | Diagnostic log level, for example `info`. | |
| DSH_CODEX_DSH_COMMAND | No | Custom path to the DSH launcher. If unset, the bridge probes the Windows default location or uses `dsh` from PATH. | |
| DSH_CODEX_ALLOWED_CWDS | No | Allowed session working directories. Directories must already exist; separate multiple directories with semicolons. | |
| DSH_CODEX_INCLUDE_THOUGHTS | No | Set to `1` to collect internal thoughts. By default internal thoughts are not returned. | |
| DSH_CODEX_MAX_OUTPUT_CHARS | No | Maximum number of characters collected for assistant/thought text; oversized tool `rawInput`/`rawOutput` values are replaced with a preview. | |
| DSH_CODEX_PROMPT_TIMEOUT_MS | No | Prompt timeout in milliseconds. | 600000 |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
This server controls DeepSeek Harness (DSH) sessions through the DSH ACP profile. Typical flow: dsh_list_sessions -> dsh_create_session or dsh_resume_session -> dsh_send_message -> dsh_close_session. Always pass an explicit session_id; the bridge never assumes "the most recent session". A resumed session continues the persisted conversation but does NOT replay prior transcript content. DSH tool permission requests are denied unless permission_policy="allow_once" is passed explicitly. DSH internal thoughts are not returned unless the bridge operator enabled DSH_CODEX_INCLUDE_THOUGHTS.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": true
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| dsh_list_sessionsA | List persisted, resumable DSH root sessions from the ACP session/list method (newest first). Optional cwd filter must be an absolute path inside the allowed directories. Returns only sessionId/cwd/title/updatedAt summaries. WARNING: sessions held by the desktop app are also listed (ACP cannot see cross-process activity); visibility does not mean the session is free. |
| dsh_create_sessionA | Create a fresh persistent DSH session via ACP session/new. cwd must be absolute, inside the configured allowlist, and is realpath-canonicalised before use. model / reasoning_effort are only accepted when explicitly allowlisted by the bridge. |
| dsh_resume_sessionA | Restore a persisted inactive DSH session via ACP session/resume, validating canonical cwd and session ownership first. Resume only restores a persisted inactive session and continues it; it does not replay prior transcript messages. WARNING: DSH ACP cannot see sessions held by another process (the desktop app), so session/list also lists sessions the desktop may still be running. Resuming is NOT read-only: it activates the session and writes to the same persisted log, which can conflict with the desktop. Requires acknowledge_released=true, and switching desktop tabs does not count as releasing. |
| dsh_send_messageA | Send one user text message to an existing session via ACP session/prompt and wait for the turn to settle. Exactly one prompt may be in flight per session. Returns the assistant text, a tool-call summary and usage. DSH internal thoughts (agent_thought_chunk) are NOT returned unless the operator set DSH_CODEX_INCLUDE_THOUGHTS. Permission requests made by DSH tools are DENIED unless permission_policy is explicitly "allow_once"; they are never auto-approved. |
| dsh_cancel_sessionA | Ask the ACP session/cancel method to stop the work of exactly one session. The in-flight prompt settles with stopReason "cancelled"; other sessions are untouched. |
| dsh_close_sessionA | Close exactly one session via ACP session/close. This cancels in-flight work, drains updates, flushes persistence, and releases the session run scope. Persisted history is retained and can be resumed later. Requires confirm=true. Closing is NOT read-only and is NOT a safe way to inspect a session; it will cancel that session's in-flight work. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 6 tools
Each tool maps to a distinct session lifecycle action: list, create, resume, send, cancel, and close. The create-vs-resume distinction is explicitly clarified (fresh session vs. persisted inactive session), and send/cancel/close operate unambiguously on active sessions.
All tools share the same dsh_ prefix and follow a consistent verb_noun snake_case pattern (list_sessions, create_session, resume_session, send_message, cancel_session, close_session). There are no mixed conventions or vague verbs.
Six tools is well-scoped for a session-lifecycle bridge and each tool earns its place. No redundant or filler operations are present.
The core lifecycle is covered (create, list, resume, send, cancel, close), but there is no tool to inspect a session's status or retrieve its transcript/history. dsh_resume_session explicitly does not replay prior messages, so agents cannot read past session content once it is not in flight.