codex-app-mcp

English · Русский

Run and follow Codex coding tasks from your MCP client.

Start work, steer a task, review changes and return to persisted goals through one connection. The bridge connects your assistant to an installed Codex app-server; your Codex login and usage remain with Codex.

⚡ Host loop (Session v1.2)

Unofficial bridge. Save host tokens:

1. codex_app_session_begin({"goal":"…","host_budget":"small"})
2. Loop codex_app_session_next → do only card (host_cmd | mcp_tool | end)
3. Stop polling when done=true, then finish with codex_app_session_end.

Skill codex-mcp v1.0 enforces this. No OAuth in MCP config — CLI login only.

Claude / Cursor orchestrate → Codex app-server works (goals, budgets, policy roots).

Unofficial community project — not OpenAI, Codex, Anthropic, or xAI.
Auth = local codex login (CODEX_HOME). Never put OAuth in MCP config or HTTP bearer.

---

Install (one command)

curl -fsSL https://raw.githubusercontent.com/zai-one/codex-mcp/main/scripts/install.sh \
  | bash -s -- --project "$HOME/code/my-project"

Windows: irm https://raw.githubusercontent.com/zai-one/codex-mcp/main/scripts/install.ps1 | iex

Then, on macOS/Linux:

codex login
source ~/.config/codex-mcp/env
~/.local/share/codex-mcp/.venv/bin/python ~/.local/share/codex-mcp/scripts/probe_stdio.py

Merge ~/.config/codex-mcp/mcp/claude_desktop.snippet.json → restart → codex_app_status.

On Windows, the installer writes %USERPROFILE%/.config/codex-mcp/env.ps1 and installs the command into %LOCALAPPDATA%/codex-mcp/.venv/Scripts/. Merge this entry into your MCP client, replacing both example paths:

{
  "mcpServers": {
    "codex": {
      "command": "C:/Users/you/AppData/Local/codex-mcp/.venv/Scripts/codex-app-mcp.exe",
      "env": {"CODEX_APP_MCP_ALLOWED_ROOTS": "C:/Users/you/code/my-project"}
    }
  }
}

Restart the connection, then ask:

Show the Codex connection status, allowed project directories and available tasks. Do not start work yet.

Skill (router): codex-mcp — see docs/SKILLS.md

Full easy guide: docs/EASY.md

Language	Page
Easy (canonical)	docs/EASY.md
EN / RU / 中文 / ES	docs/install/ (short pointers)

---

What it is

Host	Claude, Cursor, … (stdio or bearer HTTP)
Worker	Codex CLI / app-server on same machine or VPS
Why	Save host tokens under tokenBudget
Economy	CODEX_APP_MCP_ECONOMY=1 · tool codex_app_economy

Optional

• VPS · FastMCP · Economy
• Skills · Security · Reference

Built by ZAI.ONE

ZAI.ONE is a digital agency working on websites, SEO, advertising and analytics. We also build tools that connect AI assistants to everyday work. Talk to us on Telegram about setup, automation or an integration for your team.

Found a bug or need a feature? Open an issue with a redacted reproduction. If the tool helps, give it a ⭐.