Codex Antigravity MCP Server
Bridges OpenAI Codex CLI via its app-server, allowing agents to start and resume Codex sessions, send prompts, poll task progress, approve or decline runtime requests, cancel tasks, and list or inspect historical sessions.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Codex Antigravity MCP Server Start a Codex session to refactor the database module in my project"
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 Antigravity MCP Server
"GPT不说人话、不背责任不粘锅而感觉每次对话都像在打卡上班?"
"Gemini满是活人感、但智商不太够导致完全不能用?"当然是选择让Gemini去拷打gpt了!
轻量级本地MCP服务, 将OpenAI Codex CLI(codex app-server --listen stdio://)桥接封装为Antigravity、Claude Desktop、Cursor等各类 Agent 宿主可直接调用的标准服务.
核心特性
原生历史会话续接与多轮上下文恢复 (
threadId):直接复用 Codex 原生保存在
~/.codex的会话持久化存储.通过
sourceKinds: ["cli", "vscode", "exec", "appServer", "unknown"]跨越终端 CLI、VS Code 插件以及 MCP, 无缝列出并无损续接历史对话.支持向宿主 Agent 直接回显指定历史会话的消息摘要与上下文.
工作区目录与沙箱策略精准映射 (
effectiveCwd):自动规范化解析
effectiveCwd(显式传入 -> 恢复会话目录 -> 默认工作区).将权限档位精确映射为底层 Codex 沙箱策略:
supervised(默认推荐): 工作区可写 (writableRoots: [effectiveCwd]), 网络禁用, 敏感操作与终端命令由宿主代理审批 (on-request).full-access: 免审批完全访问 (danger-full-access).read-only: 只读模式, 禁用写权限与网络访问.
截断指数退避长轮询 (
10s -> 20s -> 40s, 上限45s):任务执行中未决时自动递增等待窗口, 杜绝无效的密集高频空转.
任务执行完成、触发反向审批或进程断线时即刻唤醒返回, 绝不无谓挂起.
反向代理审批闭环 (
InteractionBroker+codex_approve):完整代理并转交 Codex 运行期的各项审批: 终端命令执行、文件变更、权限扩增以及交互提问 (
user_input).实时监听服务端
serverRequest/resolved通知, 杜绝重复提交或响应已失效审批.
安全防误删可选项 (
CODEX_SAFE_TRASH):防御性拦截直接永久删除命令 (如
rm -rf,del /f,Remove-Item等), 强制要求使用回收站/垃圾箱参数.支持通过环境变量
CODEX_SAFE_TRASH=false全局关闭, 或在codex_send中传入safeTrashOnly: false进行单次覆盖.
实时状态聚合与命令尾部追踪 (
TurnTracker):内存流式汇聚 Codex 回复文本.
实时维护当前正在运行之终端命令的 4KiB UTF-8 滚动输出尾部 (
activeCommand), 方便实时查看构建或测试动态.
Related MCP server: codex-mcp-server
MCP 对外工具契约
工具名称 | 参数列表 | 功能说明 |
|
| 启动新一轮任务执行. 若存在未结束任务则返回 |
|
| 轮询当前运行中任务的最新进展. 任务完成、审批触发或超时后唤醒返回. |
|
| 回复 Codex 执行期的反向审批请求, 自动根据安全配置拦截危险删除命令. |
|
| 中断正在执行的任务, 发送 |
|
| 省略 |
环境变量说明
环境变量 | 默认值 | 作用说明 |
|
| Codex CLI 执行文件路径 (支持系统 PATH 中的 |
|
| 运行入口为 JS 脚本时所调用的 Node.js 可执行文件路径. |
|
| 当请求与续接会话均未指定目录时的默认回退工作区. |
|
| 是否全局强制启用"仅移动到垃圾箱"安全拦截规则, 设置为 |
快速上手
1. 前置依赖
Node.js >= 18.0.0
OpenAI Codex CLI 已安装并完成登录授权
2. 安装与构建
git clone https://github.com/<你的用户名>/codex-antigravity-mcp.git
cd codex-antigravity-mcp
# 安装依赖
npm install
# 编译 TypeScript 至 dist/
npm run build
# 运行自动化测试套件 (17 个用例全部通过)
npm test3. 配置接入示例
Antigravity 配置
在 Antigravity 的 MCP 配置文件中加入:
{
"mcpServers": {
"codex": {
"command": "node",
"args": [
"<你的项目绝对路径>/dist/index.js"
],
"env": {
"CODEX_BIN_PATH": "codex",
"CODEX_SAFE_TRASH": "true"
}
}
}
}Claude Desktop 配置
在 claude_desktop_config.json 中配置:
{
"mcpServers": {
"codex": {
"command": "node",
"args": [
"<你的项目绝对路径>/dist/index.js"
]
}
}
}开发与验证
# 纯类型检查 (不输出文件)
npm run typecheck
# 依据本机安装的 Codex app-server 重新生成 TypeScript 协议类型
npm run protocol:generate
# 运行单元与集成测试 (内置 fake-app-server 双向测试)
npm test
# 运行真实环境两轮长对话冒烟验收
node scripts/smoke.mjs开源协议
本项目采用 MIT 协议开源.
Available Tools
5 toolscodex_approveA
回复 Codex 的反向审批请求 (命令执行、文件更改、权限申请或用户交互提问). 会自动拦截危险的直接删除命令并转为 decline.
Inputs: turnId (required), decision (required), threadId (required), interactionId (required), +2 more.
codex_cancelA
取消当前运行中的 Codex 执行轮次. 发送中断指令并等待最多 5 秒确认. 在旧命令确认停止前保持忙碌状态以防止并发写冲突.
Inputs: turnId (required), threadId (required).
codex_pollA
轮询当前运行中的 Codex 任务进度. 未传 waitMs 时自动按截断指数退避 (20s -> 40s) 等待. 当任务完成、触发审批或断线时立刻返回.
Inputs: turnId (required), threadId (required), cursor, waitMs.
codex_sendA
向 Codex 发送提示词 (支持新建会话或在已有 threadId 上继续对话). 支持设置工作区目录、模型和权限模式. 在初始窗口 (默认 10s) 内等待, 若未完成则返回快照及下一次轮询的推荐退避时间.
Inputs: prompt (required), cwd, model, effort, +5 more.
codex_sessionsB
查看本地 Codex 原生历史会话列表或指定会话的历史对话详情. 支持覆盖全来源 (CLI / VS Code / 桌面端 / exec / appServer).
Inputs: cwd, limit, threadId.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Each tool maps to a distinct lifecycle operation: send input, poll progress, approve requests, cancel execution, or inspect sessions. The boundaries are clear even though send and poll both involve waiting, because their descriptions explain that send starts/continues work while poll only observes it.
All tools share a consistent codex_ prefix, and four of five use clear action verbs. codex_sessions is noun-based and combines list/detail behavior, which is a minor deviation from the otherwise consistent verb pattern.
Five tools are well-scoped for a Codex execution wrapper, covering the essential lifecycle without redundant endpoints. Each tool earns its place and no obvious duplicate surface exists.
The set covers sending prompts, continuing threads, polling, approvals, cancellation, and session history, which supports the core workflow. Minor gaps include no explicit session deletion or model/configuration discovery, but agents can work around these.
Maintenance
Related MCP Connectors
A paid remote MCP for OpenAI Codex agent coordination MCP, built to return verdicts, receipts, usage
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Shared memory MCP server for Claude Code, Codex, Gemini CLI and Cursor. Cited, editable.
Your org's AI agents, tasks, runs, search, and brain files as MCP tools and resources.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables MCP clients to spawn and control Codex CLI and Claude Code sessions on the host machine, with session management and filesystem access.4MIT
- AlicenseNot gradedqualityDmaintenanceWraps OpenAI Codex CLI as an MCP server, exposing 8 Codex tools (exec, review, skill list, skill run, status, poll, list jobs, kill) as named tools for use with pi or codex.1,915 npmISC
- AlicenseNot gradedqualityBmaintenanceA local stdio MCP server that lets any MCP client start a Codex thread and continue it by opaque thread ID through the codex and codex-reply tools, with fail-closed sandboxing and approval policies. It restores the removed Codex CLI MCP integration by bridging clients like OpenCode to the official Codex SDK.MIT
- AlicenseAqualityBmaintenanceEnables Claude Code or any MCP client to delegate hands-on coding work to OpenAI Codex over a persistent app-server process, keeping long-lived threads with follow-ups, async polling, approvals, steering, and interrupts. Supports native code review, resuming existing sessions, structured output, and parallel worktree-isolated tasks.1034 npm1MIT