How do I use codex-mcp-server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@codex-mcp-server review the code in src/utils/ for best practices" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

codex-mcp-server

by shilong20

Overview Schema Related Servers Score Discussions

Python

Local

codex-mcp-server

MCP server for Codex CLI — tmux persistence, git worktree isolation, async dispatch.

English | 简体中文

特性

tmux 持久化 — full-access 任务运行在 tmux session 中，网络断开、窗口关闭后任务继续执行；read-only 任务直接 subprocess 执行
git worktree 隔离 — full-access 模式自动创建独立 worktree，并行任务互不干扰
阻塞 + 异步双模式 — codex 同步等待结果，codex_dispatch 立即返回后台运行
多轮对话 (resume) — 通过 session_id 延续上一次 Codex 会话
文件系统持久化 — 任务元数据存储在 ~/.codexmcp/tasks/，服务重启后可恢复
工作区日志 — 自动在 <cwd>/.codex-tasks/ 创建 symlink，IDE 中直接查看日志

Related MCP server: tmux-mcp

工具

工具	作用	适合场景
`codex`	阻塞执行，等待完成后返回结果	代码审阅、短任务、并行模块实现
`codex_dispatch`	后台分派，立即返回 task_id	长任务（数十分钟到数小时）
`codex_status`	查询任务状态和进度	追踪后台任务、获取结果
`codex_cancel`	取消运行中的任务	终止不需要的任务

前置要求

Python 3.12+
codex CLI 已安装且在 PATH 中
tmux 已安装（full-access 模式必须）
git 已安装（full-access 模式必须）

codex --version
tmux -V
git --version

安装

从 PyPI 安装：

pip install codex-mcp-server

Claude Code

claude mcp add codex -s user --transport stdio -- \
  uvx codex-mcp-server

验证：

claude mcp list

Cursor / 通用 MCP 客户端

在 MCP 配置文件（如 mcp.json）中添加：

{
  "mcpServers": {
    "codex": {
      "command": "uvx",
      "args": ["codex-mcp-server"]
    }
  }
}

更新到最新版

uvx 会缓存已安装的包。更新到新版本时需要加 --refresh 刷新缓存：

uvx --refresh codex-mcp-server --help

注意：如果使用 PyPI 镜像源（如清华源），新版本可能需要 5-15 分钟才能同步。若 --refresh 仍拉取到旧版本，可临时指定官方源：
uvx --refresh --index-url https://pypi.org/simple/ codex-mcp-server --help

从源码安装（开发用）

git clone https://github.com/shilong20/codexmcp.git
cd codexmcp
pip install -e .

快速上手

1. 代码审阅（阻塞，只读）

{
  "tool": "codex",
  "arguments": {
    "prompt": "审阅 src/auth/ 目录的代码质量和安全性",
    "cwd": "/workspace/my-project",
    "topic": "review-auth_module-v1",
    "sandbox": "read-only"
  }
}

2. 并行模块实现（阻塞，写入）

并发调用多个 codex，每个使用不同 topic：

{
  "tool": "codex",
  "arguments": {
    "prompt": "实现用户注册模块...",
    "cwd": "/workspace/my-project",
    "topic": "implement-user_register-v1",
    "sandbox": "full-access"
  }
}

每个 full-access 任务自动创建独立的 git worktree 和分支 agent/<topic>。

3. 长任务后台分派

{
  "tool": "codex_dispatch",
  "arguments": {
    "prompt": "重构整个项目为异步架构...",
    "cwd": "/workspace/my-project",
    "topic": "longrun-async_refactor-v1",
    "sandbox": "full-access"
  }
}

立即返回 task_id。之后用 codex_status 查看进度。

4. Resume 多轮对话

首次执行返回 session_id。修改代码后继续：

{
  "tool": "codex",
  "arguments": {
    "prompt": "我已修改了代码，请重新审阅",
    "cwd": "/workspace/my-project",
    "topic": "review-auth_module-v2",
    "sandbox": "read-only",
    "session_id": "019d0aa8-..."
  }
}

resume 时 topic 版本号 +1（如 v1→v2），传入上次的 session_id。worktree 基于 <type>-<description> 生成（不含版本号），自动复用。

参数说明

参数	类型	必填	说明
`prompt`	str	是	任务指令
`cwd`	Path	是	工作目录（绝对路径）
`topic`	str	是	任务标识，格式 `<type>-<desc>-v<ver>`。用于 task_id、worktree 分支名、tmux session 名（full-access）
`sandbox`	`read-only` / `full-access`	是	权限模式。read-only 不建 worktree 不走 tmux；full-access 创建 worktree + tmux 隔离
`session_id`	str	否	恢复之前的 Codex 会话（多轮对话）

返回结构

阻塞 codex 完成后返回：

{
  "success": true,
  "task_id": "codex-implement-user_register-v1",
  "session_id": "019d0aa8-...",
  "result": "Codex 的最终回复文本",
  "exit_code": 0,
  "elapsed_seconds": 45.2,
  "usage": {"input_tokens": 5000, "output_tokens": 1200},
  "worktree_dir": "/workspace/project-agent-implement-user_register",
  "agent_branch": "agent/implement-user_register",
  "base_branch": "main",
  "diff_stat": "3 files changed, 42 insertions(+), 10 deletions(-)",
  "commits_ahead": 2
}

session_id 用于 resume
worktree 相关字段仅 full-access 模式返回
当 CODEXMCP_READONLY_FALLBACK 启用且 sandbox 为 read-only 时，返回额外的 readonly_audit 字段：

{
  "readonly_audit": {
    "mode": "fallback",
    "violations_detected": 0,
    "violations": [],
    "verdict": "CLEAN"
  }
}

verdict 为 VIOLATION 时表示检测到违规操作，violations 列出具体违规项。

环境变量

通过 MCP 服务进程环境变量配置：

变量	说明	示例
`CODEX_PROFILE`	codex 配置文件名	`fast`
`CODEX_REASONING_EFFORT`	推理强度	`high`、`xhigh`
`CODEXMCP_READONLY_FALLBACK`	容器环境下启用 read-only 降级模式（见下方说明）	`1`

Read-Only 降级模式

在 Docker 等容器环境中，read-only sandbox 可能因 bwrap namespace 限制无法正常工作。设置 CODEXMCP_READONLY_FALLBACK=1 后：

read-only 请求内部使用 danger-full-access 执行
自动注入强约束提示词，禁止任何文件修改操作
任务完成后自动审计日志，检测违规操作
返回结果中附加 readonly_audit 字段

执行路径不变：不创建 tmux session 和 git worktree，仍走 subprocess 直接执行。

日志

位置	路径
工作区 symlink	`<cwd>/.codex-tasks/<topic>/codex-exec.log`
主存储	`~/.codexmcp/tasks/<task_id>/codex-exec.log`
实时查看	`tmux attach -t codex-<topic>`（仅 full-access）

开发

git clone https://github.com/shilong20/codexmcp.git
cd codexmcp
pip install -e .

许可证

MIT License

Available Tools

4 tools

codexA

Execute a Codex task and block until completion. Use read-only sandbox for reviews/analysis, full-access for code modifications. full-access mode creates a git worktree for isolation. Returns the final result, session_id (for resume), and git diff stats.

ParametersJSON Schema

Name	Required	Description
`prompt`	Yes
`cwd`	Yes
`topic`	Yes
`sandbox`	Yes	Permission mode. read-only for reviews/analysis, full-access for code writing (creates git worktree).
`session_id`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.1/5.0

Behavior4/5

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

Discloses blocking behavior, git worktree creation for full-access, and return values (final result, session_id, git diff stats). No annotations are present, but description handles behavioral disclosure well without contradictions.

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?

Three concise sentences with no redundancy. The primary purpose is front-loaded, and each sentence adds necessary information without superfluous detail.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Provides adequate overview of behavior and return values. However, several parameters (cwd, topic, prompt) are not fully explained, and the output schema is not detailed. Given the tool's complexity, slightly more detail would improve completeness.

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 low (20%). The description adds value for 'sandbox' (already described in schema) and 'session_id' (resume context). However, 'prompt', 'cwd', and 'topic' lack explanation, requiring some inference from parameter names.

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?

The description clearly states 'Execute a Codex task and block until completion,' specifying the verb and resource. It distinguishes from siblings like codex_cancel and codex_dispatch by highlighting synchronous behavior.

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?

Provides explicit guidance on when to use read-only vs full-access sandbox modes ('Use read-only sandbox for reviews/analysis, full-access for code modifications'). Lacks comparison with sibling tools but adequately covers the key parameter choice.

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

codex_cancelA

Cancel a running Codex task by killing its tmux session.

ParametersJSON Schema

Name	Required	Description	Default
`task_id`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A3.5/5.0

Behavior3/5

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

The description reveals the mechanism (killing tmux session), indicating a forceful termination. However, with no annotations, it fails to disclose side effects like data loss or reversibility, leaving some behavioral ambiguity.

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?

The description is a single sentence that is direct and front-loaded with the action. However, it is overly terse and could benefit from additional context without being wasteful.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple cancellation tool with one parameter and an output schema, the description explains the purpose and mechanism. However, the lack of parameter documentation reduces completeness, though the output schema may compensate for return values.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 0% description coverage for the single required parameter 'task_id'. The description does not explain what task_id represents or how to obtain it, forcing the agent to infer from the tool name alone.

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?

The description clearly states the tool cancels a running Codex task by killing its tmux session. This specific verb and resource distinguish it from siblings like codex_dispatch (submit tasks) and codex_status (check status).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies the tool is for canceling running tasks, but provides no explicit guidance on when to use it versus alternatives like waiting for completion or other cancellation methods. No exclusions or prerequisites are mentioned.

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

codex_dispatchA

Dispatch a long-running Codex task to background and return immediately. The task runs in a persistent tmux session that survives disconnects. Use codex_status to check progress and codex_cancel to stop.

ParametersJSON Schema

Name	Required	Description
`prompt`	Yes
`cwd`	Yes
`topic`	Yes
`sandbox`	Yes	Permission mode. read-only for reviews/analysis, full-access for code writing (creates git worktree).
`session_id`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A3.6/5.0

Behavior3/5

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

No annotations are provided, so the description carries the burden. It discloses key behaviors: non-blocking, persistent tmux session, survival of disconnects. However, it omits details on error handling, concurrency, and sandbox side effects (e.g., full-access creates git worktree).

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 two sentences, front-loading the core action and returning immediately. Every word adds value with no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 5 parameters with low schema coverage and no annotations, the description is minimal. It covers the main purpose and lifecycle, but lacks details on input parameters and output (though output schema exists). It is adequate but has clear gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With only 20% schema coverage (only sandbox has a description), the description adds no information about any parameters. The 5 parameters, including required ones like prompt, cwd, and topic, are left unexplained, offering no additional meaning.

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?

The description clearly states the tool dispatches a long-running Codex task to background, returns immediately, and runs in a persistent tmux session. It distinguishes from siblings by referencing codex_status and codex_cancel.

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?

The description advises to use codex_status for progress and codex_cancel for stopping, providing context for when to use alternatives. However, it does not explicitly contrast with the sibling tool 'codex' or state when not to use this tool.

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

codex_statusA

Check task status. Pass task_id for single task detail (with progress events if running, or result/diff if completed). Omit task_id to list all tasks.

ParametersJSON Schema

Name	Required	Description	Default
`task_id`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.6/5.0

Behavior4/5

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

Discloses that with task_id it returns progress events if running or result/diff if completed. No annotations provided, but description covers behavioral traits adequately.

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?

Two sentences, front-loaded with purpose, no wasted words. Every sentence adds value.

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?

Given optional parameter and output schema, description covers all needed context: both modes, what to expect in output (progress/result/diff). No gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema has 0% coverage, but description fully explains the single optional parameter task_id: its two roles (single vs list), adding crucial meaning beyond 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?

Description clearly states 'Check task status' and distinguishes two modes (single task vs list all), making it distinct from siblings like codex_dispatch or codex_cancel.

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?

Explicitly tells when to use each mode: pass task_id for single detail, omit for list. Lacks explicit exclusions but context is clear.

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

4 tool updatesv1.2.2May 26, 2026
- First observedcodex
- First observedcodex_cancel
- First observedcodex_dispatch
- First observedcodex_status

Install Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4/5.0

Disambiguation5/5

Each tool has a distinct role: run blocking, run async, check status, cancel. No overlap or ambiguity.

Naming Consistency4/5

Three tools use the codex_ prefix (codex_dispatch, codex_status, codex_cancel), while the main tool is just 'codex'. This minor inconsistency is acceptable as the base tool is the primary action.

Tool Count5/5

4 tools are well-scoped for managing Codex tasks: execute (sync), dispatch (async), status, cancel. No unnecessary tools.

Completeness4/5

Covers core lifecycle (start, background, status, cancel). A resume functionality is hinted via session_id but not a separate tool, which is a minor gap.

Maintenance

ActivityInactive

ResponsivenessSyncing

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

mcp-serverOAuth
com.niftypm
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Project Management Communication File Systems
2
Apuchat A
io.github.opcastil11
Real-time chat for AI agents. Claude Code, Cursor, Cline and Codex join channels over MCP.
Communication Agent Orchestration
181
siGit
si.sigit
MCP server for siGit (sigit.si): browse repos, search code, manage PRs/issues, web search.
Version Control Developer Tools
221
slimaOAuth
io.github.slima-ai
MCP Server for Slima - AI Writing IDE for Novel Authors with AI Beta Reader.
Developer Tools
21

Related MCP Servers

mcp-tmux
Shell Access Command Line
laszlopere
A
license
B
quality
B
maintenance
A comprehensive MCP server for driving tmux sessions, windows, panes, sending keystrokes, and reading pane output locally or over SSH, enabling real-time collaborative pairing with AI.
Updated 3 months ago (2026-06-19 04:00 UTC)
71
1
MIT
tmux-mcp
Shell Access Command Line
trolleydodger1988
F
license
A
quality
D
maintenance
A persistent, stateful MCP server that exposes a detached tmux session to clients, enabling shell command execution, terminal buffer reading, and control signal sending via JSON-RPC over stdio.
Updated 3 months ago (2026-06-12 15:50 UTC)
3
-
claude-tmux
Coding Agents Autonomous Agents Agent Orchestration
Ilm-Alan
A
license
A
quality
D
maintenance
MCP server for orchestrating multiple Claude Code instances via tmux, enabling spawning, reading, sending, listing, and killing sessions.
Updated 8 months ago (2026-01-21 20:31 UTC)
5
18
2
MIT
Claude Code Subagent MCP
Coding Agents Command Line Version Control
ltxzs
A
license
A
quality
B
maintenance
A stdio MCP server that lets Codex Desktop/CLI delegate implementation tasks to Claude Code CLI with workspace validation, Git status checks, and session resume capabilities.
Updated 2 months ago (2026-07-18 15:00 UTC)
2
4
MIT

Appeared in Searches

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/shilong20/codexmcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server