Codex Delegate MCP

Overview Schema Source Related Servers Discussions Admin

delegate

Destructive

Sends coding tasks to OpenAI Codex with workspace, spec, and mode settings; check run status before trusting results and resume threads for follow-up work.

Instructions

Delegate a coding task to OpenAI Codex. Never run codex from the shell — use this tool. Check status before trusting result — a run that spawns then fails returns normally. Set spec, workspace and mode, plus resumeThreadId to resume and reviewTarget in review; leave every other field at its default unless the user asks. See the delegate skill.

Input Schema

Name	Required	Description	Default
`fast`	No	Codex Fast mode; higher credit use.
`mode`	No	agent implements; plan returns a structured plan; ask answers; review runs native review.	agent
`spec`	Yes	Brief with goal, scope, fixed decisions quoted exactly, and acceptance criteria; reference files instead of pasting code.
`model`	No	Codex model id. doctor deep:true lists every id.	gpt-6-luna
`timeoutMs`	No	Whole-run cap in ms (default 1h). Mid-turn silence is allowed; startup has a separate 60s first-output deadline.
`webSearch`	No	Codex's built-in web search.
`workspace`	Yes	Codex's working directory; not confinement. Must already exist — never create one for the call.
`reviewTarget`	No	Required in review; forbidden otherwise: uncommitted, base branch, or commit.
`resumeThreadId`	No	Thread to continue. Reuse its workspace. Forbidden with review.
`reasoningEffort`	No	Codex reasoning level. doctor deep:true lists each model's levels.	xhigh

Schema Changelog

Changes observed during successful MCP inspections.

Changed6 schema fields changedv2.5.0Oct 5, 2026

changedInput schema / properties / model / default

Previous value: -"gpt-5.6-luna"New value: +"gpt-6-luna"

changedInput schema / properties / model / description

Previous value: -"Codex model id: gpt-5.6-luna, gpt-6-luna, gpt-6-sol, gpt-6-astra, gpt-5.6-sol, gpt-5.6-terra, gpt-5.5."New value: +"Codex model id. doctor deep:true lists every id."

changedInput schema / properties / reasoningEffort / description

Previous value: -"minimal is rejected by every published model; none is rejected by gpt-6-astra and accepted elsewhere, though the catalog omits it."New value: +"Codex reasoning level. doctor deep:true lists each model's levels."

removedInput schema / properties / reasoningEffort / enum

Removed value: -[
-  "none",
-  "minimal",
-  "low",
-  "medium",
-  "high",
-  "xhigh",
-  "max",
-  "ultra"
-]

removedInput schema / properties / reviewTarget / anyOf

Removed value: -[
-  {
-    "additionalProperties": false,
-    "properties": {
-      "kind": {
-        "const": "uncommitted",
-        "type": "string"
-      }
-    },
-    "required": [
-      "kind"
-    ],
-    "type": "object"
-  },
-  {
-    "additionalProperties": false,
-    "properties": {
-      "branch": {
-        "type": "string"
-      },
-      "kind": {
-        "const": "base",
-        "type": "string"
-      }
-    },
-    "required": [
-      "kind",
-      "branch"
-    ],
-    "type": "object"
-  },
-  {
-    "additionalProperties": false,
-    "properties": {
-      "kind": {
-        "const": "commit",
-        "type": "string"
-      },
-      "sha": {
-        "type": "string"
-      }
-    },
-    "required": [
-      "kind",
-      "sha"
-    ],
-    "type": "object"
-  }
-]

addedInput schema / properties / reviewTarget / oneOf

Added value: +[
+  {
+    "additionalProperties": false,
+    "properties": {
+      "kind": {
+        "const": "uncommitted",
+        "type": "string"
+      }
+    },
+    "required": [
+      "kind"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "branch": {
+        "type": "string"
+      },
+      "kind": {
+        "const": "base",
+        "type": "string"
+      }
+    },
+    "required": [
+      "kind",
+      "branch"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "kind": {
+        "const": "commit",
+        "type": "string"
+      },
+      "sha": {
+        "type": "string"
+      }
+    },
+    "required": [
+      "kind",
+      "sha"
+    ],
+    "type": "object"
+  }
+]

Changed2 schema fields changedv2.3.0Sep 30, 2026

changedInput schema / properties / model / description

Previous value: -"Codex model id: gpt-5.6-luna, gpt-5.6-sol, gpt-5.6-terra, gpt-5.5, gpt-5.4, gpt-5.4-mini."New value: +"Codex model id: gpt-5.6-luna, gpt-6-luna, gpt-6-sol, gpt-6-astra, gpt-5.6-sol, gpt-5.6-terra, gpt-5.5."

changedInput schema / properties / reasoningEffort / description

Previous value: -"minimal is rejected by every published model; none is accepted though the catalog omits it."New value: +"minimal is rejected by every published model; none is rejected by gpt-6-astra and accepted elsewhere, though the catalog omits it."

Changed1 schema field changedv2.2.1Sep 5, 2026

changedInput schema / properties / reasoningEffort / description

Previous value: -"gpt-5.6-* reject minimal; older models reject none."New value: +"minimal is rejected by every published model; none is accepted though the catalog omits it."

Changed6 schema fields changedv2.0.0Aug 26, 2026

changedInput schema / properties / model / default

Previous value: -"gpt-5.6-terra"New value: +"gpt-5.6-luna"

changedInput schema / properties / model / description

Previous value: -"Codex model id: gpt-5.6-terra, gpt-5.6-sol, gpt-5.6-luna, gpt-5.5, gpt-5.4, gpt-5.4-mini and more."New value: +"Codex model id: gpt-5.6-luna, gpt-5.6-sol, gpt-5.6-terra, gpt-5.5, gpt-5.4, gpt-5.4-mini."

changedInput schema / properties / reasoningEffort / default
```
Previous value: -"high"New value: +"xhigh"
```

changedInput schema / properties / reasoningEffort / enum

Previous value: -[
-  "none",
-  "minimal",
-  "low",
-  "medium",
-  "high",
-  "xhigh",
-  "max"
-]New value: +[
+  "none",
+  "minimal",
+  "low",
+  "medium",
+  "high",
+  "xhigh",
+  "max",
+  "ultra"
+]

changedInput schema / properties / workspace / description

Previous value: -"Codex's working directory; not confinement. Must already exist — never create one for the call. Defaults to the server cwd, often not the project root under npx/plugin. Required on resume: resume has no --cd."New value: +"Codex's working directory; not confinement. Must already exist — never create one for the call."

changedInput schema / required

Previous value: -[
-  "spec"
-]New value: +[
+  "spec",
+  "workspace"
+]

Changed11 schema fields changedv1.21.1Aug 14, 2026

changedInput schema / properties / fast / description

Previous value: -"Codex Fast mode (service_tier=fast) — higher credit use"New value: +"Codex Fast mode; higher credit use."

addedInput schema / properties / mode / description

Added value: +"agent implements; plan returns a structured plan; ask answers; review runs native review."

changedInput schema / properties / model / description

Previous value: -"Codex model id"New value: +"Codex model id: gpt-5.6-terra, gpt-5.6-sol, gpt-5.6-luna, gpt-5.5, gpt-5.4, gpt-5.4-mini and more."

removedInput schema / properties / network

Removed value: -{
-  "default": true,
-  "description": "Web search, and network from Codex's shell in agent mode. false seals the run",
-  "type": "boolean"
-}

changedInput schema / properties / reasoningEffort / description

Previous value: -"Reasoning effort. gpt-5.6-* reject minimal; older models reject none"New value: +"gpt-5.6-* reject minimal; older models reject none."

changedInput schema / properties / resumeThreadId / description

Previous value: -"Resume an existing Codex thread instead of starting a new one"New value: +"Thread to continue. Reuse its workspace. Forbidden with review."

changedInput schema / properties / reviewTarget / description

Previous value: -"Required in review mode: uncommitted, base branch, or commit sha"New value: +"Required in review; forbidden otherwise: uncommitted, base branch, or commit."

changedInput schema / properties / spec / description

Previous value: -"Task brief: goal, scope, decisions already made (quote the user's exact values), acceptance criteria. Point at files to read rather than pasting code."New value: +"Brief with goal, scope, fixed decisions quoted exactly, and acceptance criteria; reference files instead of pasting code."

changedInput schema / properties / timeoutMs / description

Previous value: -"Hard-cap timeout in milliseconds (default 1h). A long silent command is not a timeout; only the 60s spawn-to-first-output deadline is."New value: +"Whole-run cap in ms (default 1h). Mid-turn silence is allowed; startup has a separate 60s first-output deadline."

addedInput schema / properties / webSearch

Added value: +{
+  "default": true,
+  "description": "Codex's built-in web search.",
+  "type": "boolean"
+}

changedInput schema / properties / workspace / description

Previous value: -"Working directory for Codex. Optional; defaults to the server process cwd, which for npx and plugin launches is not necessarily your project root — pass it explicitly. Smallest directory holding the task's files; none → project root. Must already exist — never create one for the call. Required when resuming: codex exec resume has no --cd."New value: +"Codex's working directory; not confinement. Must already exist — never create one for the call. Defaults to the server cwd, often not the project root under npx/plugin. Required on resume: resume has no --cd."

Changed3 schema fields changedv1.18.1Aug 11, 2026

changedInput schema / properties / reasoningEffort / enum

Previous value: -[
-  "none",
-  "minimal",
-  "low",
-  "medium",
-  "high",
-  "xhigh"
-]New value: +[
+  "none",
+  "minimal",
+  "low",
+  "medium",
+  "high",
+  "xhigh",
+  "max"
+]

changedInput schema / properties / workspace / description

Previous value: -"Working directory for Codex (defaults to cwd)"New value: +"Working directory for Codex. Optional; defaults to the server process cwd, which for npx and plugin launches is not necessarily your project root — pass it explicitly. Smallest directory holding the task's files; none → project root. Must already exist — never create one for the call. Required when resuming: codex exec resume has no --cd."

changedOutput schema / (root)

Previous value: -{
-  "$schema": "http://json-schema.org/draft-07/schema#",
-  "additionalProperties": true,
-  "properties": {
-    "cliVersion": {
-      "type": "string"
-    },
-    "delegationId": {
-      "type": "string"
-    },
-    "exitCode": {
-      "type": "integer"
-    },
-    "filesReportedByEditTools": {
-      "items": {
-        "type": "string"
-      },
-      "type": "array"
-    },
-    "plan": {
-      "additionalProperties": false,
-      "properties": {
-        "overview": {
-          "type": "string"
-        },
-        "steps": {
-          "items": {
-            "additionalProperties": false,
-            "properties": {
-              "detail": {
-                "type": "string"
-              },
-              "title": {
-                "type": "string"
-              }
-            },
-            "required": [
-              "title",
-              "detail"
-            ],
-            "type": "object"
-          },
-          "type": "array"
-        }
-      },
-      "required": [
-        "overview",
-        "steps"
-      ],
-      "type": "object"
-    },
-    "reason": {
-      "enum": [
-        "cancelled",
-        "startup-timeout",
-        "hard-cap",
-        "agent-error",
-        "died-mid-turn",
-        "exit-nonzero"
-      ],
-      "type": "string"
-    },
-    "result": {
-      "type": "string"
-    },
-    "resultSource": {
-      "const": "stream-fallback",
-      "type": "string"
-    },
-    "resumed": {
-      "type": "boolean"
-    },
-    "status": {
-      "enum": [
-        "completed",
-        "failed",
-        "interrupted"
-      ],
-      "type": "string"
-    },
-    "threadId": {
-      "type": "string"
-    },
-    "usage": {
-      "additionalProperties": false,
-      "properties": {
-        "cacheWriteInputTokens": {
-          "type": "number"
-        },
-        "cachedInputTokens": {
-          "type": "number"
-        },
-        "inputTokens": {
-          "type": "number"
-        },
-        "outputTokens": {
-          "type": "number"
-        },
-        "reasoningOutputTokens": {
-          "type": "number"
-        }
-      },
-      "type": "object"
-    },
-    "warnings": {
-      "items": {
-        "type": "string"
-      },
-      "type": "array"
-    },
-    "workspace": {
-      "type": "string"
-    }
-  },
-  "required": [
-    "result",
-    "status",
-    "workspace"
-  ],
-  "type": "object"
-}New value: +null

Changed1 schema field changedv1.14.1Aug 10, 2026
- addedOutput schema / properties / delegationId
```
Added value: +{
+  "type": "string"
+}
```
First observedv1.11.0Aug 3, 2026

TDQS

A4/5.0

Behavior4/5

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

Annotations already disclose that this is a destructive, non-idempotent, open-world operation. The description adds important behavioral context beyond annotations: a run may spawn and then fail while still returning normally, so status should be checked before trusting the result.

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 four tight sentences with the purpose and critical warning front-loaded. Each sentence provides actionable guidance without repeating schema text unnecessarily.

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 complex, destructive, open-world tool with full parameter schema coverage, the description covers the major safety and invocation gotchas. It does not explain the return format or how status should be checked, which is a gap given there is no 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 description coverage is 100%, so the schema already carries detailed meaning for every parameter. The description reinforces required fields, conditional fields, and the default policy, but it does not add substantial syntax or semantics beyond what the schema already documents.

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

Purpose4/5

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

The description states a specific verb and resource: delegate a coding task to OpenAI Codex. It is clear what the tool does, but it does not differentiate from the listed siblings cancel and doctor; it only distinguishes from running Codex via the shell.

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?

It gives strong usage guidance: use this tool instead of the shell, check status before trusting a result, set the core fields, use resumeThreadId to resume, use reviewTarget in review, and leave other fields at defaults. The missing piece is explicit routing relative to the sibling tools cancel and doctor.

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

Deploy Server

delegate

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools