Codex Delegate

What Codex Delegate does

Codex Delegate routes coding tasks from an MCP client to the OpenAI Codex CLI. The calling agent can prepare the task brief, ask Codex to make changes in a workspace, and then review the returned result. This separates orchestration and review from implementation while leaving the edits in the selected working directory.

Results are structured around the work performed. A completed delegation can include Codex's final response, status, files reported as changed by its edit tools, cumulative thread token usage, the thread ID, the delegation ID, the workspace, and the Codex CLI version. Fields without useful information are omitted.

The server fits coding-agent workflows where implementation should be delegated to Codex rather than executed directly by the host agent. It also supports non-editing questions and review tasks, so it can be used before or after a code change.

How it works

The MCP client launches the server as a stdio process. Codex Delegate invokes the locally installed OpenAI Codex CLI and associates work with a Codex thread. A later request can continue that context by supplying its thread ID; the response indicates whether the context was successfully resumed.

Delegations can be run independently, including against separate directories, or several models can be given the same question. Cancellation accepts a delegation ID for one run or a thread ID for all active runs on that thread. With neither identifier, it cancels all active runs. Cancellation waits for settlement and reports when a process remains alive beyond the kill deadline.

The doctor tool checks the plugin and CLI, login state, recursion conditions, and workspace. Its default workspace is the server's current working directory; the deep mode also checks quota-related help and the model catalog.

Setup and configuration

Install Node.js 20 or newer and install the OpenAI Codex CLI. Log in to Codex with codex login before using the server.

A standard configuration runs the package through npx:

{
  "mcpServers": {
    "codex-delegate": {
      "command": "npx",
      "args": ["-y", "codex-delegate-mcp"]
    }
  }
}

Cursor can add the server from its MCP settings or project configuration. VS Code uses an equivalent stdio entry under servers; JetBrains AI Assistant accepts the mcpServers form. Claude Code and GitHub Copilot CLI can install the repository plugin, or Copilot CLI can add the server directly. Devin Desktop, formerly Windsurf, uses its MCP configuration file. Visual Studio supports the stdio configuration in supported releases.

Tools and capabilities

• delegate sends a coding request to Codex. Its supported modes include plan, agent, ask, and review.
• plan returns schema-validated implementation steps for approval, while agent carries out the approved work on the same thread.
• ask handles questions without requiring an implementation run.
• review checks uncommitted work, a base branch, or a single commit with Codex's reviewer.
• cancel stops active work and reports whether the selected run was cancelled, already inactive, or not found.
• doctor diagnoses installation, authentication, recursion, workspace, quota-help, and model-catalog conditions.
• Thread resumption uses resumeThreadId, and resumed: false signals that prior context was not retained.

Limitations and notes

Codex must be installed and logged in separately from the MCP server. Delegated usage is charged or metered through the Codex side rather than the orchestrating chat session. The server's cancellation response can return while a surviving process tree is still running after the kill deadline; the delegate result warns about that condition.

A delegation ID is announced during progress before the Codex process starts and is the handle to use if startup wedges. Keep the default model, reasoningEffort, and fast settings unless the user requests different values. Devin Desktop's Cascade agent limits the total number of tools across all configured servers to 100.