Skip to main content
Glama
revive123456

dsh-codex-mcp

by revive123456
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Local

dsh-codex-mcp

Hand a job to the Codex CLI on your machine and get the result back in a form you can review — without giving Codex write access to your project.

What it does

  • Runs one Codex task. Give it a complete job — "review this plan", "review this patch" — and it runs codex exec and brings back Codex's answer.

  • Keeps Codex away from your files. Codex works in its own temporary folder. It can read your project, but it can only write inside that folder.

  • Hands you a list, not a wall of text. You get Codex's answer plus a list of the files it produced, with their size and a sha256 checksum. You open what you need, decide, and copy in only what you approve.

  • One tool, one job. Nothing else to learn or configure.

Typical uses: reviewing a plan, reviewing a patch or a pull request, getting a second opinion.

Related MCP server: Codex to OpenCode MCP Server

Requirements

  • Node.js 22.19+ or 24+

  • A working codex CLI on the same machine, already logged in

Install

  1. Add this block to the end of ~/.dsh/profiles/<your-profile>/cordis.patch.yml, replacing every /absolute/path/... with a real path:

- insert:
    - id: mcp-codex
      name: '@deepseek-ai/dsh-mcp-client'
      config:
        transport: stdio
        serverName: codex
        command: /absolute/path/to/node
        args:
          - /absolute/path/to/dsh-codex-mcp/src/server.mjs
        cwd: /absolute/path/to/your/workspace
        toolCallTimeoutMs: 900000
        failOnStartupError: true

  1. Restart the DSH app once. (In practice it also works without a restart — when we tested it, the new row was live in the same session.)

You now have one new tool: mcp__codex__run.

Usage

Ask your agent for a review and it calls the tool for you. The arguments:

Argument

Required

What it means

prompt

yes

The whole job, written out. Codex cannot see your chat, so include the paths it should read and the file name it should write.

model

no

Which Codex model to use, for example gpt-6-astra for careful reviews. Defaults to your Codex setting.

files

no

Report only these files. Defaults to everything the run created.

timeoutMs

no

How long the run may take, in milliseconds. Default: 15 minutes.

What comes back looks like this:

ok  exit=0  140.1s  model=gpt-6-astra  terminal=yes
run        run-20260925-181307-9c44
artifact   /path/to/your/workspace/.codex-staging/run-20260925-181307-9c44/work
manifest   /path/to/your/workspace/.codex-staging/run-20260925-181307-9c44/manifest.json
final message
-------------
review written to review.md
artifacts (1) — bodies are NOT included, read them yourself
-------------
    2500 B  sha256:6676042702213315  review.md

artifact is the folder Codex was allowed to write. Open the files listed under it, read them, then copy the parts you agree with into your project.

Tip: put a size limit in your prompt ("at most 60 lines", "top 5 risks only"). Long answers can be cut off by the model provider; short, structured ones come back reliably.

Command line (optional)

The same engine, handy for trying things by hand:

codex-mcp run -p "Review the plan at plan/foo.md and write review.md" -m gpt-6-astra
codex-mcp runs                                  # list finished runs
codex-mcp prune --older-than-days 7 --keep 5    # clear old temporary runs
codex-mcp env                                   # show how Codex will be started

Settings (optional)

Variable

What it does

CODEX_MCP_ENTRY

Full path to the codex program, if it is not found automatically.

CODEX_MCP_MODEL

Default model when a call does not name one.

CODEX_MCP_TIMEOUT_MS

Default time limit for a run.

CODEX_MCP_STAGING_DIR

Where temporary run folders go. Default: <your-workspace>/.codex-staging.

Safety

  • Codex can read your project, but it can only write inside the temporary folder for that run.

  • Commands Codex runs cannot reach the network, so it cannot upload your files.

  • Codex uses its own login. This tool never reads, stores or forwards your keys.

  • Nothing Codex produces enters your project by itself — you decide what to copy.

Development

node --test tests/*.test.mjs

The tests are offline: they use a fake Codex, so they never call a model and cost nothing. For a real run there is scripts/live-review.mjs — that one does cost money.

License

MIT.

Available Tools

1 tool
runA

Run one Codex CLI task (codex exec) in an isolated scratch directory. Returns Codex's final message plus an artifact manifest (path, bytes, sha256 per file) — file bodies are NEVER included. Codex can read the workspace but can only write inside its own scratch directory. Read the artifact paths yourself, review them, and only then copy what you approve into the workspace.

ParametersJSON Schema
NameRequiredDescriptionDefault
filesNoOptional explicit list of artifact paths (relative to the artifact root) to report. Omit to report every file the run created.
modelNoOptional Codex model id for this call (for example gpt-6-astra for plan review). Omit to use the deployment default from CODEX_MCP_MODEL, or Codex's own configuration.
promptYesThe complete, self-contained task for Codex. It does not share this conversation, so include everything it needs (paths it may read, the exact question, and the output file it should write).
timeoutMsNoDeadline in milliseconds for the whole run. Defaults to the deployment value (CODEX_MCP_TIMEOUT_MS, else 900000).

TDQS

A4.5/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It discloses the isolation boundary, that file bodies are NEVER included, that Codex lacks conversation context, and the required review-then-copy workflow. This is rich behavioral context well beyond what the schema provides.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, each earning its place: execution mode, return format, and post-run agent responsibilities. Information is front-loaded and there is no fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a sandboxed execution tool with four fully documented parameters and no output schema, the description fully covers what to expect, what the agent must do, and the safety boundary. The manifest description compensates for the missing output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so all parameters are already documented. The description reinforces the prompt's self-contained requirement and the scratch-directory context, adding some value, but does not introduce new parameter-level details beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb 'Run' + resource 'Codex CLI task' + the isolation mode, and clearly distinguishes what the tool returns (final message plus artifact manifest, not file bodies). It is immediately clear what this tool does and how it differs from a plain shell executor.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides clear workflow guidance: Codex cannot see conversation context, so the prompt must be self-contained; Codex can read the workspace but write only in scratch; the agent must read artifacts and approve before copying. Lacks an explicit 'use X instead when...' alternative, but the context is otherwise well-specified.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 1 tool updatev0.1.0
    • First observedrun
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.7/5.0

Scored across 1 tool

Disambiguation5/5

With only one tool, there is no possibility of confusing it with another operation. The tool's purpose—running a Codex CLI task in an isolated scratch directory—is singular and clearly bounded.

Naming Consistency5/5

A single tool cannot exhibit internal naming inconsistency. The name 'run' is a simple imperative verb that matches the server's single action, even though there is no broader verb_noun pattern to evaluate.

Tool Count5/5

The server's stated purpose is to run one Codex CLI task, so a single tool is appropriately scoped rather than thin. Adding extra tools for the same action would be redundant; the tool is substantial rather than trivial.

Completeness5/5

The tool covers the full intended workflow: it executes Codex, returns the final message, and provides an artifact manifest with paths and hashes so the agent can review and copy approved files. There are no obvious missing lifecycle operations because the server is intentionally a stateless task runner.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers