Skip to main content
Glama
jgt87

codex-offload-mcp

by jgt87
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Local

codex-offload-mcp

An MCP server for running Claude Code and the Codex CLI as a pair: Claude drives, and hands self-contained tasks to Codex as background jobs.

codex_start returns a job id immediately instead of blocking, so the driving model keeps working while Codex works alongside it — two agents on the problem at once, rather than one waiting on the other.

Why this exists

To use two coding models together rather than one at a time. Claude Code holds the conversation, the context and the judgment about what to do next; Codex is a capable second agent that can be given a well-specified piece of work and left to get on with it. Neither replaces the other, and the interesting part is what they do concurrently.

Blocking would defeat the entire point. If handing work to Codex meant waiting for Codex, there would be no pair — just one model parked while the other runs, which is strictly worse than doing the work yourself. So dispatch returns in about a second and the job continues in a detached process that outlives even this server. The driving model carries on reasoning, reading and answering, and collects the result when it is ready.

That concurrency is also what makes the delegation worth specifying carefully. Codex cannot see the conversation, so a task has to travel as a complete brief — and the work that comes back is checked against git rather than taken on trust, because handing work between models is precisely where "I did the thing" and "the thing got done" come apart.

Related MCP server: Codex Bridge

Tools

Tool

Returns

codex_start

{ jobId, state, … } — immediately, job runs in the background

codex_execute_plan

{ jobId, … } — hand Codex a finished plan to carry out faithfully

codex_status

State, elapsed time, commands run, files touched, recent activity

codex_result

Structured handoff report + git-verified changes; progress if still running

codex_reply

Continues a job's Codex thread with a follow-up; returns a new jobId

codex_models

Available models and the reasoning efforts each one accepts

codex_cancel

Kills the job and its child processes

codex_list

Known jobs, newest first, optionally filtered by state

None of them block.

The handoff

Getting work back from Codex matters as much as sending it. Three things make the return trip trustworthy:

1. A typed report. Jobs run with --output-schema, so the final message is not prose but a fixed shape:

{
  "summary": "...",
  "status": "complete | partial | blocked",
  "filesChanged": [{ "path": "...", "change": "..." }],
  "verification": [{ "command": "...", "passed": false, "details": "..." }],
  "followUps": ["..."],
  "blockers": ["..."],
  "documentation": "which docs were updated, or why none were warranted",
  "confidence": "high | medium | low"
}

This makes Codex commit to whether it actually finished and whether its checks passed, instead of burying a failed test in a paragraph. Pass structured: false for a job where you want prose.

2. Changes verified against git, not self-reported. codex_result also returns actualChanges, computed by diffing the repo against the commit and dirty-file set recorded when the job started. Files already modified beforehand are flagged preexisting so they are not mistaken for Codex's work. When the report and actualChanges disagree, actualChanges is the one to trust.

3. A way to push back. codex_reply continues the original Codex thread, so corrections ("you missed the error path", "now update the tests") land with all of Codex's context intact rather than starting a cold job that has to rediscover everything.

Install

Prerequisites

  • Node.js 20+

  • The Codex CLI, installed and authenticated — run codex login and confirm codex --version works. This server drives that binary; without it every job fails immediately.

Build

git clone https://github.com/jgt87/codex-offload-mcp.git
cd codex-offload-mcp
npm install
npm run build

This produces dist/index.js. Note its absolute path — every step below needs it.

Add to VS Code

MCP support is built into current VS Code; if the Command Palette lists MCP: commands, you have it. Pick either route:

Guided. Command Palette (Ctrl+Shift+P) → MCP: Add Server → Command (stdio). Enter node as the command and the absolute path to dist/index.js as the argument, then name it codex-offload.

By hand. Command Palette → MCP: Open User Configuration to open your user mcp.json (%APPDATA%\Code\User\mcp.json on Windows), and add the server:

{
  "servers": {
    "codex-offload": {
      "type": "stdio",
      "command": "node",
      "args": ["C:/path/to/codex-offload-mcp/dist/index.js"]
    }
  }
}

Use forward slashes on Windows, or escape backslashes as \\ — a raw C:\path is invalid JSON and the server will silently fail to start.

To scope it to one project instead of your whole profile, use MCP: Open Workspace Folder Configuration and put the same servers block in .vscode/mcp.json. That file can be committed, which gives everyone on the repo the same tools.

Verify. Open the Chat view, switch to Agent mode, click Configure Tools, and confirm the codex_* tools appear and are enabled. MCP: List Servers shows the server's status and its logs if it failed to start.

Add to Claude Code

claude mcp add codex-offload --scope user -- node /absolute/path/to/dist/index.js

Confirm with /mcp in a session, or claude mcp list from a shell.

After changing the code

A running server keeps serving the old dist/, so rebuild and restart it:

npm run build

  • VS Code — MCP: List Servers → select the server → Restart. (The experimental chat.mcp.autoStart setting can do this for you.)

  • Claude Code — restart the session; MCP servers connect at session start.

Using it

You do not call the tools by name. Ask for what you want and Claude selects them:

You say

Tool

"Offload to Codex: migrate the auth module to the new API"

codex_start → jobId, immediately

"How's that Codex job doing?"

codex_status

"Get the Codex result"

codex_result

"Tell Codex it missed the error path"

codex_reply

"What Codex jobs are running?"

codex_list

"Which models can Codex use?"

codex_models

"Kill that job"

codex_cancel

The pattern worth building a habit around is dispatch-then-continue: "Offload the test migration to Codex, and while that runs, walk me through the router."

Checking its work

codex_result gives you Codex's own report and actualChanges from git. When they disagree, git wins. For anything that matters, go further than reading the report: run the tests, and break the thing under test to confirm they actually fail. A suite that passes proves less than a suite you have watched fail for the right reason.

Collaboration modes

One-shot offload — hand Codex a task, collect the result — is the base case. On top of it are a few named ways to split work between the two models, each with a slash command so you can start one from any repo. Install the commands by copying them into your Claude Code commands directory:

cp .claude/commands/*.md ~/.claude/commands/

Command

Pattern

Who does what

/codex-plan-execute <task>

plan → execute

Claude designs the change and writes a concrete plan; Codex carries it out faithfully in the background.

/codex-review <task>

execute → review

Codex does the work; Claude reviews the git diff and sends corrections with codex_reply.

/codex-split <task>

split & parallelize

Claude decomposes the task into independent chunks and dispatches several Codex jobs at once, then reassembles.

/codex-draft <task>

draft → refine

Codex produces a fast first draft cheaply; Claude refines it in-process where context and taste are needed.

The split is the same one the whole server is built on: the reasoning, the judgement and the conversation context stay with Claude; the expensive output tokens — typing out a plan, a bulk draft, a mechanical migration — go to Codex, which bills separately. Three of the four modes need no new code; they are patterns over codex_start, codex_result and codex_reply, named and given a front door.

plan→execute is the exception — it has machinery of its own. It adds a tool, codex_execute_plan, that takes a finished plan rather than an open task. Codex is told the plan came from another model and to follow it faithfully — and, crucially, to stop and report a blocker instead of quietly substituting its own design when a step is wrong, so you can revise the plan and resume with codex_reply. Because the design thinking is already done and lives in the plan, execution usually needs less reasoning effort than the whole task would; routing still reads the plan text and effort stays overridable, so pin a lower reasoningEffort when the steps are mechanical.

It fits the same seam as the documentation instruction: the faithful-execution framing is prepended to what Codex receives, but codex_status and codex_list still show the plan you actually handed over, not the machinery around it.

Orchestration

Two decisions get made per task, and they are handled very differently.

Whether to delegate is not decided here. There is no scheduler, no queue and no second model triaging work. The only thing steering that choice is the codex_start tool description, which the calling model reads at call time and judges against.

That is deliberate. The decision needs the one thing this process cannot see — the conversation. Whether a task is self-contained, whether there is useful work to do while it runs, whether you are about to change your mind about the approach: none of that is visible from inside an MCP server, so the judgment stays with the model that has the context, and this server sticks to running the job and checking the result. Editing that description in src/index.ts is how you change delegation behaviour in general.

One dial you can turn without touching code: how much to offload. The whether-decision stays the model's, but you can bias it. Set the CODEX_MCP_OFFLOAD_LEVEL environment variable on the server to conservative, balanced (the default) or aggressive, and it appends a matching instruction to the codex_start description the model reads — aggressive lowers the bar so more work goes to Codex (useful when you want to conserve Claude's own usage), conservative raises it. It steers judgment rather than enforcing a rule: the hard exclusions — needs conversation context, exploratory, trivial triage — still hold at every level. It is read once at startup, so restart the server after changing it, and codex_models reports the active setting so you can confirm it took. In your MCP config it goes in the server's env block:

{
  "servers": {
    "codex-offload": {
      "type": "stdio",
      "command": "node",
      "args": ["C:/path/to/codex-offload-mcp/dist/index.js"],
      "env": { "CODEX_MCP_OFFLOAD_LEVEL": "aggressive" }
    }
  }
}

Which model and how hard it thinks are decided here — see below. That part is a genuine heuristic, and the honest framing is that it is the one invented thing in the pipeline: no API reports "this task is mechanical". So it is built to be inspectable rather than trusted. Every job records the tier and the reason it was picked, and any explicit value overrides it.

What should be offloaded

All of these need to hold:

Test

Why

Self-contained

Codex cannot see the conversation. Anything resting on what was just worked out must be restated in full — and if restating it is most of the work, offloading is a net loss.

Slow

Minutes, not seconds. Below ~30s the round trip costs more than it saves.

Real work to do meanwhile

Dispatching and then sitting on codex_status gains nothing.

Verifiable afterwards

Mechanical enough that actualChanges from git shows whether it went right.

Scoped to one cwd

Codex writes to disk directly; ambiguous scope means unwanted edits.

Keep it in-process when the task needs conversation context, is fast, blocks the next decision, or is surgical enough that specifying it precisely costs more than just doing it.

Exploratory work is the main trap. Investigations where each measurement changes what you look at next cannot be offloaded — by the time the prompt can be written, the thinking is already done. A useful tell is a wrong hypothesis: if you expect to have one, keep the work in-process.

Misjudging is asymmetric. A bad question wastes a minute; a bad delegation writes files to disk. That asymmetry is why codex_result checks Codex's self-report against git instead of trusting it — the design already assumes a delegation can be wrong. Prefer sandbox: "read-only" for anything analytical.

Choosing model and effort

codex_start picks both from the task text unless you pass them. Here is the whole path a call takes, from prompt to spawned process:

codex_start(prompt, model?, reasoningEffort?, autoRoute?)
   │
   ├── autoRoute: false ────────────────────► skip everything below
   │                                          (caller's values, else config.toml)
   ▼
classify(prompt)                              src/route.ts — keyword match, no model call
   │
   ├── matches HARD patterns?      ── yes ──► tier = hard
   ├── matches MECHANICAL patterns? ─ yes ──► tier = mechanical
   └── neither ─────────────────────────────► tier = standard          (hard wins ties)
   │
   ▼
pick model            match tier's wording against each model's vendor description
   │                  ("frontier" / "balanced" / "fast, affordable")
   │                  no match → Codex's own first-ranked model
   ▼
pick effort           mechanical → low   standard → medium   hard → high
   │
   ▼
clamp to model        effort not in this model's supported list?
   │                  → nearest supported level at or below it
   ▼
apply overrides       explicit model / reasoningEffort replace whatever was chosen
   │
   ▼
validate              model accepts this effort?
   │                        │
   │                        └── no ──► error returned in ms, nothing spawned
   ▼
spawn `codex exec --json` detached, recording {tier, rationale, auto} on the job

Only the classify step is invented. Everything from "pick model" down is driven by the model index Codex itself maintains, so the lineup and the legal effort levels are facts rather than guesses.

The tiers:

Tier

Signals

Effort

Model

mechanical

renames, moving files, formatting, typos, applying a stated pattern

low

the one described as fast/affordable

standard

anything without a strong signal — the default

medium

the one described as balanced/everyday

hard

concurrency, races, deadlocks, leaks, security, architecture, trade-offs, root-cause work

high

the one described as frontier

A prompt matching both mechanical and hard is treated as hard: under-thinking a subtle problem costs more than over-thinking a simple one.

Resolved against a real lineup, the assignment looks like this — the model column is whatever the index currently offers, not a fixed list:

  TASK                                         TIER          MODEL            EFFORT
  ───────────────────────────────────────────  ────────────  ───────────────  ──────
  "Rename getUser to fetchUser across the      mechanical    gpt-5.6-luna     low
   repo and update the call sites"             │             fast, affordable
                                               └─ matched: "rename"

  "Add an endpoint returning the current       standard      gpt-5.6-terra    medium
   user's projects"                            │             balanced/everyday
                                               └─ no strong signal → default

  "Fix the race condition in the job           hard          gpt-5.6-sol      high
   scheduler that drops events under load"     │             frontier
                                               └─ matched: "race condition"

  "Rename the lock helper while fixing the     hard          gpt-5.6-sol      high
   deadlock it causes"                         │
                                               └─ matched both; hard wins

The model lineup is discovered, not hardcoded. Models and their accepted effort levels are read from Codex's own index (~/.codex/models_cache.json), so a model released after this server was written is picked up automatically. Routing re-reads the index whenever Codex rewrites it (the file's mtime changes), so a long-running server keeps up with Codex rotating or dropping models instead of routing to one that no longer exists and failing the job after it spawns. Tiers map onto that lineup by matching the vendor's own descriptions, which means a renamed model still routes sensibly. codex_models reports the current lineup, including whether the index was actually readable. (The model names shown inside the tool descriptions are still the startup snapshot — schema text is fixed for an MCP session — so a restart refreshes those, but routing itself does not need one.)

This matters more than it sounds. The first version of this feature hardcoded the effort list, and it was wrong within the hour — it invented none and minimal, which no model advertises, and omitted ultra, which two models support.

Effort is clamped to what the chosen model accepts, so a model topping out at xhigh never receives ultra. If you pin a model and an effort it cannot take, the call fails immediately with the model's real list — rather than failing the job minutes later, which is what Codex does on its own, since it forwards the value unchecked.

Overriding. An explicit model or reasoningEffort always wins, and partial pinning works — fix the model, let the effort be routed, or the reverse. autoRoute: false disables inference entirely and falls back to your ~/.codex/config.toml defaults. Worth knowing that if that file sets model_reasoning_effort = "high", every un-routed job runs at high until you say otherwise.

Every job records what was chosen and why:

"routing": {
  "tier": "mechanical",
  "rationale": "classified as mechanical — matched mechanical wording (rename); model gpt-5.6-luna chosen for this tier; effort low",
  "auto": true
}

The classifier is keyword matching, and deliberately so — a cleverer one would need a model call, which would add latency to a tool whose whole promise is returning immediately. It will misread things. That is why it explains itself and why every part of it can be overridden.

codex_reply takes reasoningEffort too, defaulting to the parent job's. Worth raising when a first attempt failed for want of thinking, and lowering when the follow-up is a mechanical fixup.

The feedback loop

Work does not come back trusted. Every job produces two independent accounts of itself, and the loop closes by comparing them:

  codex_start
      │    git baseline captured first: current commit + already-dirty files
      ▼
  codex exec --json   (detached — outlives this server)
      │    streams events.jsonl while it works
      ▼
  codex_status  ──  poll as often as you like; never blocks
      │
      ▼
  codex_result
      │
      ├───────────────────────────┐
      ▼                           ▼
  Codex's report             actualChanges
  what it believes it did    what git says changed,
  summary, verification,     measured against the
  confidence                 baseline above; files
      │                      already dirty flagged
      │                      preexisting
      │                           │
      └─────────────┬─────────────┘
                    ▼
           caller compares them   ── git wins any disagreement
                    │
         ┌──────────┴───────────┐
         ▼                      ▼
   agree, tests pass      disagree, or partial
         │                      │
         ▼                      ▼
      accept              codex_reply
                                │
                                ▼
                 new job on the SAME Codex thread
                 full context retained, effort adjustable
                                │
                                └──►  back to codex_status, above

Three properties make this worth the machinery:

The two accounts are produced independently. The report is what Codex says; actualChanges is computed by diffing the repo against the baseline captured before the job started. Files you had already modified are flagged preexisting, so they are never mistaken for Codex's work. When the two disagree, git wins.

The correction path keeps context. codex_reply resumes the original thread by its thread_id, so "you missed the error path" lands with everything Codex already knows, instead of a cold job that has to rediscover the codebase.

The loop is closed by you, not by the router. Nothing here learns. A job records its tier and rationale so you can look back and see whether the classification was reasonable, but a misrouted task does not adjust anything for next time — you pin model or reasoningEffort on the retry, or edit the patterns in src/route.ts. If routing keeps getting a particular kind of task wrong, that is a signal to change the keyword lists, and it is meant to be done by hand.

How it works

What happens when a task is offloaded

  1. Baseline. codex_start records the state of cwd before Codex touches anything: the current commit, plus the set of files already dirty. This is what makes the later verification honest — files you had already modified are flagged preexisting rather than blamed on Codex.

  2. Routing. Unless you pinned them, model and reasoning effort are chosen from the task text and clamped to what that model accepts. An effort the model cannot take is rejected here, before anything is spawned.

  3. Dispatch. The prompt is written to prompt.txt and codex exec --json is spawned detached, with the prompt fed over stdin. The call returns a job id immediately; nothing blocks, ever.

  4. Streaming. Codex writes JSONL events to events.jsonl as it works, and its final answer to last-message.txt. Both are on disk, not in memory.

  5. Polling. codex_status parses the tail of the event stream into a progress view — commands run, files touched, recent activity. It reports; it never waits.

  6. Collection. codex_result returns Codex's structured report and re-diffs the repo against the baseline from step 1 to produce actualChanges. Two independent accounts of the same work.

  7. Follow-up. codex_reply resumes the original Codex thread by its thread_id, so a correction lands with all of Codex's context intact rather than starting cold.

Under the hood

Each job spawns codex exec --json as a detached process, with:

  • the prompt piped over stdin — no command-line length or quoting limits

  • --json events streamed to events.jsonl (parsed for the progress view)

  • -o last-message.txt capturing the final answer

  • metadata in meta.json

Jobs live in ~/.codex-mcp/jobs/<jobId>/ (override with CODEX_MCP_JOBS_DIR). Finished jobs older than seven days are pruned at startup.

Because jobs are detached, they survive this server restarting. A job started by a previous process has nobody listening for its exit, so running is only trusted while its pid is alive; otherwise state is recovered from whether a result file was produced.

The Codex binary is resolved to the real platform executable inside the npm package, so jobs spawn with an argv array rather than through a shell. Override with CODEX_BIN if needed.

Sandbox

sandbox defaults to workspace-write: Codex may edit files under cwd. That is the point — it does real work — but it means the working tree changes underneath you. Re-read files after a job finishes rather than trusting anything cached from before.

  • read-only — analysis and review, no writes

  • workspace-write (default) — edits within cwd (plus any addDirs)

  • danger-full-access — unrestricted; only when explicitly asked for

Cancelling does not roll back edits already made.

Documentation

Jobs that can write are asked to document themselves. A standing instruction is appended to the prompt telling Codex to update the project's existing documentation — README.md, AGENTS.md, CLAUDE.md, files under docs/ — when the change alters behaviour, adds a feature, or makes an existing statement untrue.

This exists because Codex starts cold. It cannot see the conversation that led to the task, so unless something asks, documentation simply never gets written and the caller has to remember every single time.

The instruction leans hard in one direction: edit what exists, do not create new files. An unqualified "document your changes" reliably produces a CHANGES.md or NOTES.md in every repository it touches, which is worse than nothing — it fragments what a reader has to consult and goes stale immediately. Codex is told not to invent a changelog, to match the surrounding document's voice and structure, and to prioritise correcting statements the change made untrue over adding new prose. It is also told to skip documentation when the work does not warrant it, and to say so.

The structured report carries a required documentation field, so a job has to account for what it wrote or explain why it wrote nothing. actualChanges from git shows which .md files were actually touched, so the claim is checkable rather than taken on faith — the same split the rest of the handoff uses.

Setting

Behaviour

default

On for workspace-write and danger-full-access

documentation: false

Suppressed; the prompt is passed through untouched

sandbox: "read-only"

Always off — the job could not write a file even if asked

A codex_reply follow-up inherits the parent job's setting, so a correction to documented work keeps the docs in step with it. The instruction is appended only to what Codex receives; codex_status and codex_list still show the prompt you actually wrote.

Writing good job prompts

Codex starts cold. It cannot see the Claude conversation, so a prompt must carry its own context: what to change, which files, the constraints, and what "done" looks like.

Available Tools

8 tools
codex_cancelCancel a Codex jobA

Stop a running job and its child processes. Any file edits Codex already made stay on disk — cancelling does not roll anything back.

ParametersJSON Schema
NameRequiredDescriptionDefault
jobIdYesId returned by codex_start.

TDQS

A4.1/5.0
Behavior4/5

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

Discloses key side effect: file edits stay on disk and cancelling does not rollback. This adds value beyond the basic cancel action, especially since no annotations are provided.

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?

Two sentences, no wasted words. First sentence states the action, second adds critical behavioral detail. Efficient and well-structured.

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 simple 1-parameter tool with no output schema, the description is fully sufficient. It explains what happens (stop job and child processes) and important caveats (no rollback).

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% and the parameter jobId is described as 'Id returned by codex_start.' The description adds no extra meaning beyond the schema, meeting the baseline.

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?

The description clearly states 'Stop a running job and its child processes,' using a specific verb and resource. It distinguishes from sibling tools like codex_start (starts) and codex_status (checks status) by focusing on cancellation.

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

Usage Guidelines3/5

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

No explicit guidance on when to use vs alternatives. The description implies it's for stopping jobs but doesn't contrast with other tools or state when not to use it.

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

codex_execute_planHand Codex a plan to executeA

The execute half of plan→execute: you do the design thinking in this conversation, write a concrete step-by-step plan, and hand it here for Codex to carry out in the background — getting a jobId back immediately, exactly like codex_start. Codex is told the plan was authored by another model and to follow it faithfully rather than redesign: if a step is wrong or impossible it stops and reports in blockers instead of improvising, so you can revise and resume with codex_reply. Reach for this when the hard part was deciding what to do and the rest is faithful typing across files — it keeps the reasoning on your side and the output tokens on Codex's. Because the design is already done, the execution usually needs less reasoning effort than the planning did, so consider pinning a lower reasoningEffort unless individual steps are themselves subtle. The plan must be self-contained: Codex cannot see this conversation, so state every step, file, and acceptance check in the plan text itself. Keep working while it runs; check codex_status when you need to and collect the result with codex_result, which checks what Codex did against git — don't re-check in a tight loop, since each check is a model turn.

ParametersJSON Schema
NameRequiredDescriptionDefault
cwdYesAbsolute path to the directory Codex should treat as its working root.
planYesThe step-by-step plan for Codex to execute. Write it as an ordered list of concrete steps naming the files to touch and what each change is, plus how to tell it worked (tests to run, behaviour to check). Self-contained: Codex cannot see this conversation.
modelNoPin the model instead of letting it be chosen from the plan. Available: (model index unavailable; Codex config defaults apply). Omit to let routing pick one.
addDirsNoExtra absolute directories Codex may write to, beyond cwd.
sandboxNoread-only = cannot modify anything; workspace-write (default) = may edit files under cwd; danger-full-access = unrestricted, avoid unless the caller explicitly asked for it.
autoRouteNoDefault true. Set false to use only the values you pass (or Codex defaults).
structuredNoDefault true: Codex returns a typed handoff report. Set false only for long prose where the structure would get in the way.
documentationNoDefault true for jobs that can write: Codex updates existing docs the change makes untrue and reports what it touched. Set false to suppress. Always off under read-only.
reasoningEffortNoHow hard Codex should think while executing. The planning is already done, so mechanical execution can take a lower setting than the task as a whole would — raise it only when individual steps are themselves subtle. Omit to let routing choose from the plan text.

TDQS

A4.6/5.0
Behavior4/5

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

With no annotations, the description handles the burden well. It explains that Codex follows faithfully, stops on blockers, and cannot see the conversation. It mentions returning a jobId immediately and working in background. However, it could explicitly mention that the tool modifies files based on sandbox settings, though that is covered in parameter descriptions.

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

Conciseness4/5

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

The description is a single paragraph that front-loads the core purpose and then provides detailed usage guidance. While not overly verbose, it could be slightly more concise (e.g., 'the execute half of plan→execute' is a bit redundant). Still, every sentence contributes meaning.

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

Completeness4/5

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

Given no output schema, the description mentions returning a jobId but doesn't fully specify the return format or structure. However, for a tool with 9 parameters and complex behavior, it covers the essential aspects: execution model, blocking behavior, plan requirements, and post-execution flow via codex_result.

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

Parameters5/5

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

Schema coverage is 100%, but the description adds significant context beyond the schema: for 'plan' it stresses self-containment and structure, for 'reasoningEffort' it gives nuanced guidance on when to lower it, and for 'sandbox' it explains defaults and warnings. This extra information helps the agent choose appropriate values.

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?

The description clearly identifies this as the execution half of a plan-execute split, with specific verb 'hand' and resource 'plan'. It distinguishes itself from codex_start by emphasizing the pre-planned nature and from other siblings like codex_status and codex_result by stating it returns a jobId immediately and is for background execution.

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

Usage Guidelines5/5

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

The description explicitly states when to use this tool: 'Reach for this when the hard part was deciding what to do and the rest is faithful typing across files.' It provides guidance on when not to use it implicitly, mentions alternatives like codex_reply for blockers, and gives tips on reasoningEffort and plan self-containment.

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

codex_listList Codex jobsA

List known jobs, newest first, with their current state. Use this to find a jobId you lost track of, or to check whether anything is still running.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNoDefault 20.
stateNoOnly return jobs in this state.

TDQS

A4/5.0
Behavior3/5

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

No annotations are provided, so the description must carry the full burden. It discloses that results are ordered newest first and include current state, but does not mention pagination, rate limits, or that it is a read-only operation. While not misleading, it leaves gaps in behavioral understanding.

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?

The description is extremely concise — two sentences that front-load the purpose and usage context. Every word adds value, with no repetition or fluff.

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

Completeness4/5

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

For a simple list tool with two optional parameters, the description covers the primary function and common use cases. It could mention the output format (e.g., array of job objects) since there is no output schema, but the current level is adequate for basic understanding.

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 description coverage is 100%, so the baseline is 3. The description adds no additional meaning beyond the schema's descriptions for limit and state — the parameters are straightforward and self-explanatory.

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?

The description clearly states the tool lists jobs newest first with their current state, and provides specific use cases like finding a lost jobId or checking if anything is still running. This distinguishes it from sibling tools like codex_status or codex_cancel.

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?

The description explicitly says when to use the tool ('find a jobId you lost track of, or to check whether anything is still running'), giving contextual guidance. However, it does not explicitly mention alternatives or when not to use it, but the use cases imply differentiation.

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

codex_modelsList available Codex modelsA

Show the models this Codex install offers and the reasoning efforts each one accepts, read from Codex's own model index. Use it when you want to pin model or reasoningEffort on codex_start and need to know what is legal — the accepted efforts differ per model, and a value the model does not take fails the job rather than the call. Also reports how the index was obtained, so a stale or missing one is visible rather than silent.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.9/5.0
Behavior5/5

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

With no annotations, the description fully discloses the source (Codex's own model index) and that it reports how the index was obtained, making staleness or missing data visible.

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?

Well-structured with the main purpose front-loaded, and every sentence adds value without redundancy.

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?

Given zero parameters and no output schema, the description is remarkably complete, covering usage, data source, and potential issues (stale index).

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

Parameters4/5

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

There are no parameters, so baseline is 4. The description adds no parameter-specific details but fully compensates by explaining the tool's purpose and output.

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?

The description clearly states the tool shows available Codex models and their reasoning efforts, distinguishing it from sibling tools like codex_start by focusing on listing rather than execution.

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

Usage Guidelines5/5

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

Explicitly advises when to use: when pinning model or reasoningEffort on codex_start, and warns that invalid values fail the job, not the call, providing clear guidance.

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

codex_replyFollow up on a Codex jobA

Send a follow-up into a finished job's Codex thread — corrections, review comments, 'you missed X', 'now do Y as well'. Codex retains everything from the original job, so this is far better than starting a fresh job that would begin cold. Returns a new jobId you collect exactly like codex_start — keep working while it runs rather than re-checking in a loop. The follow-up reuses the original job's working directory and sandbox.

ParametersJSON Schema
NameRequiredDescriptionDefault
jobIdYesThe job to continue. May itself be a previous codex_reply job.
promptYesThe follow-up message for Codex.
structuredNoWhether to require a typed report. Defaults to the parent job's setting.
reasoningEffortNoReasoning effort for this follow-up. Defaults to the parent job's setting. Worth raising when the first attempt got it wrong for want of thinking, and worth lowering when the follow-up is a mechanical fixup of work already done.

TDQS

A4.4/5.0
Behavior4/5

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

With no annotations provided, the description carries the full burden. It discloses key behavioral traits: it returns a new jobId, advises to keep working while it runs (avoid re-checking), and states that it reuses the original working directory and sandbox. It also notes that Codex retains context from the original job. The description does not explicitly state if the operation is destructive or safe, but the nature of sending a follow-up implies a non-destructive mutation.

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?

The description is concise with four sentences. It is front-loaded with the core purpose, then adds critical details (retains context, return value, reuse of directory). Every sentence adds value without redundancy or fluff.

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

Completeness4/5

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

Given the tool has 4 parameters and no output schema, the description adequately explains the tool's behavior and return value (new jobId). It covers the key use case and workflow. Minor omissions like error handling are forgivable, as this is a follow-up tool that builds on existing jobs.

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

Parameters4/5

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

Schema description coverage is 100%, so baseline is 3. The description adds valuable context beyond the schema: for 'reasoningEffort', it provides strategic guidance on when to raise or lower the effort; for 'jobId', it clarifies that it can be a previous codex_reply job. The general explanation of the tool enriches understanding of parameter purpose.

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?

The description clearly states the verb 'Send a follow-up' and the resource 'finished job's Codex thread'. It provides concrete examples of usage ('corrections, review comments, 'you missed X', 'now do Y as well') and distinguishes itself from the sibling tool 'codex_start' by emphasizing the benefit of retaining context. The purpose is specific and unambiguous.

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?

The description explicitly states that this tool is 'far better than starting a fresh job that would begin cold', giving a clear when-to-use recommendation. It implies when not to use (when a fresh start is needed) and contrasts with 'codex_start'. However, it does not mention other sibling tools like 'codex_execute_plan' or 'codex_result', but the primary alternative is covered.

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

codex_resultCollect a Codex job's outputA

Collect a finished job's handoff: Codex's structured report (what it did, what it verified, what it left undone, how confident it is) alongside actualChanges — the file changes according to git, independent of what Codex claims. Trust actualChanges over the report when they disagree, and re-read any changed file before reasoning about it. If the job is still running this returns progress instead; it never blocks.

ParametersJSON Schema
NameRequiredDescriptionDefault
jobIdYesId returned by codex_start.
includeActivityNoAlso return the full trace of what Codex did to get there.

TDQS

A4.6/5.0
Behavior5/5

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

No annotations provided, so description carries full burden. It discloses key behaviors: returns report and actualChanges, trust actualChanges over report, non-blocking progress return, and job completion requirement. Highly transparent.

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?

Single, well-structured paragraph front-loaded with the purpose. Every sentence provides useful information without redundancy. Length is appropriate for the tool's complexity.

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

Completeness4/5

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

For a tool with 2 parameters and no output schema, the description adequately explains the return content (report with specifics, actualChanges). Still, a more detailed template of the report could improve completeness, but current level is sufficient.

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

Parameters4/5

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

Schema covers both parameters with descriptions. The description adds value by linking jobId to codex_start and explaining that includeActivity returns the full trace, enriching the schema information.

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?

Description clearly states the tool collects a finished Codex job's output, specifying the structured report and actualChanges. It distinguishes itself from sibling tools like codex_status and codex_cancel by focusing on final output collection.

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 guidance on when to use (after job finishes) and what to expect (progress if still running). Includes a practical tip to trust actualChanges over the report. Lacks explicit comparison to alternative tools but is generally sufficient.

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

codex_startStart a Codex jobA

Hand a coding task to the Codex CLI and get a jobId back immediately — Codex runs in the background while you keep working. Two reasons to reach for it. One: the task is self-contained and slow (refactors, migrations, test writing, bulk edits across files), so running it in the background buys concurrency. Two: the task is self-contained and output-heavy (generating a lot of code, tests, or boilerplate), so letting Codex produce those tokens conserves your own usage — this reason holds even when the task is fast, because you and Codex bill separately. Codex edits files on disk directly in cwd, so treat the working tree as modified once the job finishes. Keep working while it runs; check codex_status when you need to and collect the answer with codex_result — don't re-check in a tight loop, since each check is a model turn. Still the wrong tool for a quick question you need answered right now, and for trivial triage or classification (relevance filtering, labelling, risky-or-not) send those to a local model instead — this returns a job id, not an answer, so anything cheaper to resolve another way should be. Model and reasoning effort are chosen automatically from the task text unless you set them; the choice and its reasoning come back in the response, and setting either one explicitly overrides it. Call codex_models to see what is available.

ParametersJSON Schema
NameRequiredDescriptionDefault
cwdYesAbsolute path to the directory Codex should treat as its working root.
modelNoPin the model instead of letting it be chosen from the task. Available: (model index unavailable; Codex config defaults apply). Omit to let routing pick one.
promptYesThe task for Codex. Be specific and self-contained: Codex cannot see this conversation, so restate the relevant context, constraints, and what 'done' looks like.
addDirsNoExtra absolute directories Codex may write to, beyond cwd.
sandboxNoread-only = cannot modify anything; workspace-write (default) = may edit files under cwd; danger-full-access = unrestricted, avoid unless the caller explicitly asked for it.
autoRouteNoDefault true. Set false to suppress automatic selection entirely and use only what you pass (or the Codex config defaults) — useful when the keyword heuristic misreads a task and you want no inference at all.
structuredNoDefault true: Codex must return a typed handoff report (summary, status, filesChanged, verification, followUps, blockers, confidence). Set false only when you want a long prose explanation and the structure would get in the way.
documentationNoDefault true for jobs that can write: Codex is asked to update the project's existing documentation when the change alters behaviour, adds a feature, or makes an existing statement untrue, and to report what it touched. It is told to edit existing docs rather than invent a changelog, and to skip when the change does not warrant any. Set false to suppress the instruction. Always off under read-only, which cannot write.
reasoningEffortNoHow hard the model should think, overriding your Codex config for this job only. Match it to the task: 'low' for mechanical work where the answer is obvious and the cost is typing (renames, moving files, applying a stated pattern); 'medium' for ordinary implementation; 'high' or 'xhigh' for genuinely hard reasoning — tricky concurrency, subtle logic, design decisions with real trade-offs. Higher settings cost more and take longer, so raising it for simple work buys nothing. Note that accepted values vary by model: 'none', 'low', 'medium', 'high' and 'xhigh' are widely supported, while 'minimal' and 'max' are rejected by some models and will fail the job on its first API call. Omit to inherit the config default.

TDQS

A4.9/5.0
Behavior5/5

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

No annotations are present, so the description bears full responsibility. It fully discloses that Codex edits files on disk in cwd, that jobs run in the background, and warns against tight polling loops. It explains automatic model/reasoning-effort selection, default behaviors for structured, documentation, and autoRoute, and the implications of each sandbox setting.

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

Conciseness4/5

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

The description is lengthy (over 400 words) but every sentence serves a purpose. It is front-loaded with the core action and use cases, then systematically covers behavioral details and parameter guidance. While slightly verbose, the density of information justifies the length.

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?

Given 9 parameters, no output schema, and no annotations, the description covers all necessary behavioral and contextual details: what is returned (jobId), how to interact with sibling tools (status, result), file system effects, parameter defaults, and when to override each. It is thorough and leaves no obvious gaps.

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

Parameters5/5

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

Schema description coverage is 100%, but the description significantly enriches each parameter beyond the schema. It explains when to set structured=false (long prose), why documentation defaults true, how reasoningEffort maps to task complexity, and the meaning of sandbox levels. This adds substantial value for an agent.

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?

The description clearly states the tool's purpose: handing a coding task to Codex CLI and receiving a jobId immediately for background execution. It specifies the verb ('hand a coding task'), resource ('Codex CLI'), and distinguishes from sibling tools by emphasizing that it returns a jobId, not an answer. The two use cases (slow tasks and output-heavy tasks) further clarify its role.

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

Usage Guidelines5/5

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

The description provides explicit when-to-use criteria (self-contained slow or output-heavy tasks) and when-not-to-use (quick questions, trivial triage/classification). It even suggests an alternative: 'send those to a local model instead.' This is comprehensive and actionable.

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

codex_statusCheck a Codex jobA

Report whether a job is still running and what it has done so far (commands run, files edited, latest messages). Cheap to call. Does not block — if the job is still running, it says so rather than waiting.

ParametersJSON Schema
NameRequiredDescriptionDefault
jobIdYesId returned by codex_start.
verboseNoInclude the full recent activity trace instead of just the last few entries.

TDQS

A4.4/5.0
Behavior5/5

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

With no annotations, the description fully discloses behavioral traits: it is non-blocking, cheap to call, and reports current status without waiting. It also details what information is returned. This is sufficient transparency for a status-check tool.

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?

The description is three sentences long, front-loaded with purpose, followed by details and behavioral notes. Every sentence adds value, and there is no redundancy or unnecessary text.

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

Completeness4/5

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

The description adequately covers the tool's behavior and returned information for a simple status check. It might lack details on error handling or exact return format, but given the low parameter count and no output schema, it is nearly complete.

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 description coverage is 100%, so baseline is 3. The description does not add meaning beyond the schema; it only restates the purpose. No additional parameter semantics are provided.

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?

The description clearly states the tool's purpose: 'Report whether a job is still running and what it has done so far'. It specifies the resource (a Codex job) and the verb (report/check), includes examples of returned information (commands run, files edited, latest messages), and distinguishes it from siblings like codex_result and codex_cancel.

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?

The description provides clear usage context: it is 'Cheap to call' and 'Does not block', suggesting it is for lightweight polling. However, it does not explicitly mention when not to use it or name alternative tools, so it falls short of a 5.

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. Dates show when Glama detected each change.

  1. 8 tool updatesv0.1.0
    • First observedcodex_cancel
    • First observedcodex_execute_plan
    • First observedcodex_list
    • First observedcodex_models
    • First observedcodex_reply
    • First observedcodex_result
    • First observedcodex_start
    • First observedcodex_status
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.5/5.0
Disambiguation5/5

Each tool has a distinct purpose: starting tasks (codex_start, codex_execute_plan), checking status (codex_status), collecting results (codex_result), canceling (codex_cancel), replying (codex_reply), listing models (codex_models), and listing jobs (codex_list). No overlap in functionality.

Naming Consistency5/5

All tools follow a consistent 'codex_' prefix followed by a clear verb or verb_noun pattern (start, execute_plan, status, result, cancel, reply, models, list), maintaining perfect naming consistency.

Tool Count5/5

8 tools is well-scoped for managing background Codex jobs: covering task initiation (two variants for different workflows), monitoring, result collection, cancellation, follow-up, model discovery, and job listing. No superfluous or missing tools.

Completeness5/5

The tool surface covers the full lifecycle of background job offloading: start (with plan variant), status, result, cancel, reply, list, and model queries. No obvious gaps for the intended domain.

Maintenance

ActivitySlowing
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • Codex Bridge

    jonwadsworth
    F
    license
    Not graded
    quality
    B
    maintenance
    A self-hosted MCP server that lets claude.ai delegate tasks to OpenAI Codex CLI, billed through the ChatGPT subscription, with tools for job submission, status polling, and result retrieval.
    -

  • agent-fleet

    baiqiaw
    A
    license
    Not graded
    quality
    D
    maintenance
    MCP server that enables Claude Code to delegate tasks to Codex for real-time collaborative code generation and execution.
    18
    MIT

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/jgt87/codex-offload-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server