Via a registered codex MCP server, call the Codex tool. MCP server startup command:codex mcp-server。
Two core tools
| Tool | Purpose |
|---|---|
codex |
Start a new Codex session, returns threadId |
codex-reply |
Continue an existing session (requires threadId） |
Scenario quick reference
| Scenario | Tool | Key parameters |
|---|---|---|
| One-off task (analysis / Q&A) | codex |
prompt, sandbox: read-only |
| Write files / implement code | codex |
prompt, approval-policy: never, sandbox: workspace-write |
| Multi-turn conversation (follow-up / modification) | codex-reply |
threadId, prompt |
| Specify a model or configuration | codex |
model, profile, config |
| Switch working directory | codex |
cwd |
Model quick reference
| Value | Description |
|---|---|
o3 |
Strongest reasoning, complex tasks |
o4-mini |
Fast and balanced, everyday tasks |
| (omitted) | Use the default model from the Codex local configuration |
Receiving results
The Codex MCP tool is request-response mode,you must await the tool return value before continuing. Response structure:
# 正确：等待响应，提取内容和 threadId
response = await mcp.call("codex", { prompt: "...", sandbox: "read-only" })
text = response.structuredContent.content # 实际文本
threadId = response.structuredContent.threadId # 多轮时保存此值
# 继续会话（多轮）
reply = await mcp.call("codex-reply", { threadId, prompt: "继续..." })
# 错误：fire-and-forget，结果和 threadId 丢失
mcp.call("codex", { prompt: "..." })
For responses, read structuredContentfirst; legacy clients fall back to reading content[0].text. If the response is empty or the tool reports an error, stop and report to the caller.
Fixed rules
- The MCP server must already be registered in the agent config, with key
codex-cli - Each tool call must wait for the response to complete before continuing
- When files need to be written, you must set both
approval-policy: neverandsandbox: workspace-write - For multi-turn sessions, you must save the
structuredContent.threadIdfrom the first response, for use in subsequentcodex-reply sandbox: danger-full-accessgrants full system permissions; use it only when the user has explicitly authorized it
See the full parameter descriptions in references/tool-specs.md。