Skip to main content
Glama
parisbs

codex-subagent-mcp

by parisbs
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

Delegate a task to Codex

codex_delegate

Delegate a task to the local Codex CLI (OpenAI's coding agent), choosing model and reasoning effort. Use it when the user asks for Codex, or when handing work off clearly serves their request: a second opinion from a different model…

Instructions

Delegate a task to the local Codex CLI (OpenAI's coding agent), choosing model and reasoning effort. Use it when the user asks for Codex, or when handing work off clearly serves their request: a second opinion from a different model family, or an investigation that would otherwise flood this conversation. When the user has not named a model, call codex_recommend first and present its suggested model and effort to the user in the same message in which you say you are going to delegate, then pass both explicitly here. That recommendation is advice for an already-authorised delegation, not a replacement for the user's own preference. Everything passed in prompt, context and target_files is sent to OpenAI, and every run spends the user's own Codex usage, so do not delegate what you can answer directly, and tell the user when you delegate. Codex runs read-only unless a different default sandbox is configured. Set sandbox to workspace-write to let it edit files, if this server's sandbox ceiling allows it: a correctly configured server states the ceiling in its instructions, and a call above it is refused. Codex cannot see this conversation, so pass everything it needs in prompt, context, and target_files.

Input Schema

NameRequiredDescriptionDefault
modeNoblocking (default) waits and streams progress; background returns a job_id immediately.
labelNoYour own short name for this kind of task, stored verbatim in the local usage log and never sent to Codex: 1 to 64 characters, no control or bidirectional-control characters. A follow-up without one keeps its thread's label.
modelNoCatalog slug from list_codex_models. If omitted, the configured default is used; with no default configured the call is refused and the recommended model is returned.
promptYesThe task for Codex. Be specific and self-contained: Codex cannot see this conversation.
contextNoBackground Codex needs: prior findings, constraints, relevant excerpts.
sandboxNoSandbox policy. Uses the configured default when omitted; without one, Codex runs read-only.
add_dirsNoAdditional absolute directories that should be writable alongside working_dir.
web_searchNoEnable Codex's API-backed live web-search tool for this run. In a read-only sandbox, shell commands have no network access, so this is the route to current external information. When omitted, Codex's own configured web_search mode applies.
working_dirNoAbsolute path Codex uses as its working root.
auto_approveNoAdds --approve-for-me so Codex auto-approves its own commands. Only applies when sandbox is workspace-write.
target_filesNoPaths Codex should focus on, relative to working_dir.
use_worktreeNoRun in a managed git worktree. Writes outside it remain subject to the sandbox policy and add_dirs.
output_schemaNoA JSON Schema object for this turn's final message, which then comes back as JSON in a delimited block. OpenAI's structured outputs apply: every object needs "additionalProperties": false and every property listed in "required". At most 64 KiB serialised.
timeout_secondsNoWall-clock budget. Defaults to 1800s.
reasoning_effortNoReasoning depth, independent of model choice. Uses the configured default or the model's default when omitted. Clamped to supported levels within the configured ceiling; refused if none qualify.
acceptance_criteriaNoConcrete conditions that must hold for the task to be considered done.
skip_git_repo_checkNoAllow running outside a git repository.
system_instructionsNoPersona or extra rules inherited from the orchestrator, layered on the built-in quality contract.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.6.0
    • addedInput schema / properties / label
      Added value: +{
+  "description": "Your own short name for this kind of task, stored verbatim in the local usage log and never sent to Codex: 1 to 64 characters, no control or bidirectional-control characters. A follow-up without one keeps its thread's label.",
+  "type": "string"
+}
  2. Changed1 schema field changedv0.4.0
    • addedInput schema / properties / output_schema
      Added value: +{
+  "additionalProperties": {},
+  "description": "A JSON Schema object for this turn's final message, which then comes back as JSON in a delimited block. OpenAI's structured outputs apply: every object needs \"additionalProperties\": false and every property listed in \"required\". At most 64 KiB serialised.",
+  "propertyNames": {
+    "type": "string"
+  },
+  "type": "object"
+}
  3. Changed2 schema fields changedv0.3.0
    • changedInput schema / properties / sandbox / description
      Previous value: -"Sandbox policy. Defaults to read-only: Codex analyses and reports but cannot modify files."New value: +"Sandbox policy. Uses the configured default when omitted; without one, Codex runs read-only."
    • changedInput schema / properties / web_search / description
      Previous value: -"Enable live web search for this run, through Codex's web_search = \"live\" setting. When omitted, Codex's own configured web_search mode applies."New value: +"Enable Codex's API-backed live web-search tool for this run. In a read-only sandbox, shell commands have no network access, so this is the route to current external information. When omitted, Codex's own configured web_search mode applies."
  4. Changed5 schema fields changedv0.2.0
    • changedInput schema / properties / auto_approve / description
      Previous value: -"Adds --approve-for-me so Codex auto-approves its own commands. Only applies when sandbox allows writes."New value: +"Adds --approve-for-me so Codex auto-approves its own commands. Only applies when sandbox is workspace-write."
    • changedInput schema / properties / model / description
      Previous value: -"Catalog slug from list_codex_models. Omitted means the recommendation matrix picks one."New value: +"Catalog slug from list_codex_models. If omitted, the configured default is used; with no default configured the call is refused and the recommended model is returned."
    • changedInput schema / properties / reasoning_effort / description
      Previous value: -"Reasoning depth, independent of model choice. Clamped to what the chosen model supports."New value: +"Reasoning depth, independent of model choice. Uses the configured default or the model's default when omitted. Clamped to supported levels within the configured ceiling; refused if none qualify."
    • changedInput schema / properties / use_worktree / description
      Previous value: -"Run in a managed git worktree so changes never touch the current working tree."New value: +"Run in a managed git worktree. Writes outside it remain subject to the sandbox policy and add_dirs."
    • changedInput schema / properties / web_search / description
      Previous value: -"Enable Codex's native web search tool."New value: +"Enable live web search for this run, through Codex's web_search = \"live\" setting. When omitted, Codex's own configured web_search mode applies."
  5. First observedv0.1.0

TDQS

A4.8/5.0
Behavior5/5

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

Annotations only declare readOnlyHint=false and openWorldHint=true; the description goes far beyond them, disclosing data egress ("Everything passed in prompt, context and target_files is sent to OpenAI"), cost (spends the user's own Codex usage), the read-only default sandbox, the server-level sandbox ceiling that can refuse a call, and the read-only-context limitation. It also prescribes user-facing behavior (tell the user when you delegate). No contradiction with annotations.

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?

Purpose and routing are front-loaded, then cost/privacy, then sandbox, which is the right order. It is a single very dense block with minor redundancy (the prompt/context/target_files data-egress point and the "Codex cannot see this conversation" point are made twice in different framings).

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 an 18-parameter, open-world, mutating delegation tool with no output schema, the description covers the gaps the schema cannot: cost, data egress, permission ceiling, defaults, and user communication. It never explains how to collect results from a background run (codex_job_status/codex_job_result), but the mode parameter's schema text covers the job_id return.

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 coverage is 100%, so the baseline is 3; the description adds meaning on top by explaining that everything in prompt, context and target_files leaves the machine, and that sandbox escalation to workspace-write depends on a server ceiling that must be stated in the server's instructions. It does not touch mode/background vs blocking behavior or how jobs are retrieved, leaving the rest to the schema.

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

Purpose5/5

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

States a specific verb and resource ("Delegate a task to the local Codex CLI (OpenAI's coding agent)") plus the two knobs it exposes, model and reasoning effort. It is clearly distinguishable from siblings like codex_recommend (advice only) and codex_follow_up (continuation), which are named with different roles.

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 says when to use it (user asks for Codex, second opinion from a different model family, investigation that would flood the conversation) and when not to ("do not delegate what you can answer directly"). It also gives an ordered prerequisite: if no model was named, call codex_recommend first and present the suggestion in the same message.

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

Deploy Server

Other Tools