Codex Delegate MCP
# Codex Delegate
**Stop burning your frontier agent's limits on boilerplate.**
Delegate implementation to the **OpenAI Codex CLI** — your agent writes the brief and reviews the diff.
[](https://www.npmjs.com/package/codex-delegate-mcp)
[](https://www.npmjs.com/package/codex-delegate-mcp)
[](https://registry.modelcontextprotocol.io/v0.1/servers?search=codex-delegate&version=latest)
[](https://glama.ai/mcp/servers/andreilungeanu/codex-delegate-mcp)
[](https://nodejs.org)
[](LICENSE)
[](https://github.com/andreilungeanu/codex-delegate-mcp/actions/workflows/test.yml)
<img src="assets/logo-light.png" alt="Codex Delegate logo" width="150" align="left" hspace="15">
Use your best coding agent where its judgment matters most: understanding the task, shaping the plan, and reviewing the result.
Codex Delegate is the MCP bridge that lets Claude Code, Cursor, Copilot — or any MCP client — hand implementation to the **OpenAI Codex CLI**, then get a clean, structured result back for review.
<br clear="left">

## 🧠 Frontier quality, kept
Your assistant does what frontier models are actually for: understands the task, writes a precise brief, reviews the finished diff. Codex holds its own as the implementer — guided and checked by a smarter orchestrator. The result reads like frontier work, because a frontier model planned it and signed off on it.
## ⚡ Done faster
Codex tears through multi-file edits while a frontier chat model would still be streaming the first file. You delegate, keep working with your assistant, and the diff shows up done.
## 🔋 Your limits stop being the bottleneck
Delegated work runs on the **OpenAI Codex CLI** and its own usage — separate from your orchestrator's chat quota, though the Codex side still bills its own way. Your Claude, Cursor, or Copilot subscription spends tokens on the brief and the review; Codex does the grinding. On API? That's the per-token grind moved off your main bill.
#


## Features
- 📦 **One result you can review** — a compact JSON block: the final answer, `status`, the files Codex's edit tools reported changing, cumulative thread token counts, and the `threadId` to continue from. Fields that carry no signal are omitted.
- 📋 **Plan first, then build it on the same thread** — `plan` returns schema-validated steps for you to approve, and `agent` implements them. `ask` answers questions. `review` runs Codex's own reviewer over uncommitted work, a base branch, or a single commit.
- 🧵 **Resume** — continue a Codex thread with `resumeThreadId`. `resumed: false` tells you the context did not carry over.
- 🧑🤝🧑 **Run several, cancel cleanly** — the same question across models, or independent workers on independent directories. `cancel` waits for the exit and warns when a process outlives the kill deadline.
- 🤝 **One-command install** — Claude Code, Google Antigravity, GitHub Copilot CLI, Cursor and VS Code take it as a plugin, with a skill that teaches your agent how to delegate well. Cursor and VS Code install the server in one click; JetBrains, Devin Desktop (Windsurf), Visual Studio and the rest add the stdio server in settings.
- 🩺 **`doctor`** — tells you exactly what's missing if setup isn't right.
## Install
You need [Node.js 20+](https://nodejs.org/) and the [OpenAI Codex CLI](https://github.com/openai/codex), already logged in (`codex login`).
### Claude Code
```shell
/plugin marketplace add andreilungeanu/codex-delegate-mcp
/plugin install codex-delegate@codex-delegate-mcp
```
Then just ask:
> Delegate to Codex: migrate src/api from callbacks to async/await and update the tests, then walk me through what changed.
That's the whole loop — Claude writes the brief, Codex grinds through the files, Claude walks you through the diff.
### Cursor
[](https://cursor.com/en/install-mcp?name=codex-delegate&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsImNvZGV4LWRlbGVnYXRlLW1jcCJdfQ%3D%3D)
Or add it under **Customize → MCPs** in the sidebar, or in `~/.cursor/mcp.json` (every project) or `.cursor/mcp.json` (this project):
```json
{
"mcpServers": {
"codex-delegate": {
"command": "npx",
"args": ["-y", "codex-delegate-mcp"]
}
}
}
```
Then ask Cursor to delegate implementation to Codex the same way.
### Google Antigravity
```shell
agy plugin install https://github.com/andreilungeanu/codex-delegate-mcp
```
Restart the Antigravity app to load it. If you added `codex-delegate` to `mcp_config.json` by hand, remove that entry.
Without the CLI, use the manual config under [More clients](#more-clients).
### GitHub Copilot CLI
```shell
copilot plugin marketplace add andreilungeanu/codex-delegate-mcp
copilot plugin install codex-delegate@codex-delegate-mcp
```
The server alone, without the skill: `copilot mcp add codex-delegate -- npx -y codex-delegate-mcp`.
### More clients
<details>
<summary><strong>VS Code</strong> — one-click install, or <code>.vscode/mcp.json</code></summary>
[](https://vscode.dev/redirect/mcp/install?name=codex-delegate&config=%7B%22type%22%3A%22stdio%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22codex-delegate-mcp%22%5D%7D)
[](https://insiders.vscode.dev/redirect/mcp/install?name=codex-delegate&config=%7B%22type%22%3A%22stdio%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22codex-delegate-mcp%22%5D%7D&quality=insiders)
```json
{
"servers": {
"codex-delegate": {
"type": "stdio",
"command": "npx",
"args": ["-y", "codex-delegate-mcp"]
}
}
}
```
Or run **Chat: Install Plugin From Source** with this repository's URL (needs the `chat.plugins.enabled` setting).
</details>
<details>
<summary><strong>JetBrains AI Assistant</strong> — Settings → Tools → AI Assistant → MCP</summary>
Under **Settings → Tools → AI Assistant → Model Context Protocol (MCP)**, click **Add** and paste this JSON:
```json
{
"mcpServers": {
"codex-delegate": {
"command": "npx",
"args": ["-y", "codex-delegate-mcp"]
}
}
}
```
</details>
<details>
<summary><strong>Devin Desktop (formerly Windsurf)</strong> — <code>~/.config/devin/mcp_config.json</code></summary>
This config is for Devin Local, the default agent (Local 3.6+). On Windows the file is `%APPDATA%\devin\mcp_config.json`. Legacy Cascade and older Windsurf builds read `~/.codeium/windsurf/mcp_config.json`.
```json
{
"mcpServers": {
"codex-delegate": {
"command": "npx",
"args": ["-y", "codex-delegate-mcp"]
}
}
}
```
Heads-up: Devin Desktop's Cascade agent caps you at 100 tools across all servers.
</details>
<details>
<summary><strong>Visual Studio 2026 / 2022</strong> — <code>%USERPROFILE%\.mcp.json</code></summary>
```json
{
"servers": {
"codex-delegate": {
"type": "stdio",
"command": "npx",
"args": ["-y", "codex-delegate-mcp"]
}
}
}
```
Visual Studio 2022 needs 17.14+. Note the top-level key is `servers`, not `mcpServers`. A `.mcp.json` in the solution directory scopes it to that solution.
</details>
<details>
<summary><strong>OpenCode</strong> — <code>~/.config/opencode/opencode.json</code> or project <code>opencode.json</code></summary>
OpenCode does **not** use `mcpServers`. Local servers go under `mcp`, with `type: "local"` and `command` as one array:
```json
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"codex-delegate": {
"type": "local",
"command": ["npx", "-y", "codex-delegate-mcp"],
"enabled": true
}
}
}
```
This is the v1 shape, which OpenCode v2 still reads (v2's native form is `mcp.servers`).
</details>
<details>
<summary><strong>Google Antigravity</strong> (without the plugin) — <code>~/.gemini/config/mcp_config.json</code> or workspace <code>.agents/mcp_config.json</code></summary>
```json
{
"mcpServers": {
"codex-delegate": {
"command": "npx",
"args": ["-y", "codex-delegate-mcp"],
"timeoutSeconds": 21660
}
}
}
```
</details>
<details>
<summary><strong>Kilo Code</strong> — <code>kilo.jsonc</code> (<code>mcp</code> key, not <code>mcpServers</code>)</summary>
Same shape as OpenCode: `type: "local"` and `command` as one array.
```json
{
"mcp": {
"codex-delegate": {
"type": "local",
"command": ["npx", "-y", "codex-delegate-mcp"],
"enabled": true
}
}
}
```
In the VS Code extension: **Settings → MCP → Add Server → Local (stdio)**. On Windows, if `npx` is not found, use command `cmd` with arguments `/c`, `npx`, `-y`, `codex-delegate-mcp`.
</details>
### Kiro and any other MCP client
Add the following server to the client's MCP config — for Kiro, `~/.kiro/settings/mcp.json` (user) or `.kiro/settings/mcp.json` (workspace):
```json
{
"mcpServers": {
"codex-delegate": {
"command": "npx",
"args": ["-y", "codex-delegate-mcp"]
}
}
}
```
MIT © [Andrei Lungeanu](https://github.com/andreilungeanu)
<sub>[Configuration](CONFIGURATION.md) · [Security](SECURITY.md) · [Privacy](PRIVACY.md) · [Terms](TERMS.md) · [Changelog](CHANGELOG.md)</sub>
TDQS
Scored across 3 tools
The three tools map to clearly separate lifecycle phases: starting a run (delegate), stopping one (cancel), and diagnosing the environment (doctor). Their scopes are orthogonal, so an agent cannot reasonably misselect between them.
All three names are single lowercase verbs (delegate, cancel, doctor), giving a predictable, readable convention. It deviates from the classic verb_noun pattern only because the domain is a single resource type, so no noun is needed.
Three tools is on the lean side but each covers a genuinely distinct need for a focused delegation plugin. Nothing feels padded or redundant, though the surface is minimal.
The delegate description tells agents to 'check status before trusting result,' yet there is no explicit status, list, or result-retrieval tool — status appears only implicitly through delegate's return value. That leaves a notable gap for inspecting or enumerating runs, even though start/cancel/diagnose is covered.