Skip to content
Back to search

codex-as-mcp

Convert codex CLI tool to an MCP — unleash the power of GPT-5

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/kky42--codex-as-mcp/badge.svg)](/listings/kky42--codex-as-mcp)

HTML

<a href="/listings/kky42--codex-as-mcp"><img src="/api/listings/kky42--codex-as-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

1. Install Codex CLI

**Requires Codex CLI >= 0.46.0**

npm install -g @openai/codex@latest
codex login

# Verify installation
codex --version

Make sure Codex CLI can run non-interactively on your machine (provider + credentials in `~/.codex/config.toml`, or via the provider-specific env var it references).

Example: third-party provider + `env_key`

If you're using a third-party provider, configure it in Codex `config.toml` and point `model_provider` at it. When a provider uses `env_key`, Codex CLI expects that env var to be present when it runs.

Example:

model_provider = "custom_provider"

[model_providers.custom_provider]
name = "custom_provider"
base_url = "https://..."
wire_api = "responses"
env_key = "PROVIDER_API_KEY"
show_raw_agent_reasoning = true

When using `codex-as-mcp`, make sure the MCP server process has that env var set, so it can pass it through to the spawned `codex` process. The env var name **must match** the `env_key` value above (here: `PROVIDER_API_KEY`).

**Option A (recommended): set env in your MCP client config (if supported)**

{
  "mcpServers": {
    "codex-subagent": {
      "type": "stdio",
      "command": "uvx",
      "args": ["codex-as-mcp@latest"],
      "env": {
        "PROVIDER_API_KEY": "KEY_VALUE"
      }
    }
  }
}

**Option B: pass env via server args**

uvx codex-as-mcp@latest --env PROVIDER_API_KEY=KEY_VALUE

**Option C: add via Codex CLI (`codex mcp add`)**

codex mcp add codex-subagent --env PROVIDER_API_KEY=KEY_VALUE -- uvx codex-as-mcp@latest

Security note: passing secrets via command-line args may be visible via process lists on your machine; prefer option A when possible.

2. Configure MCP

Add to your `.mcp.json`:

{
  "mcpServers": {
    "codex-subagent": {
      "type": "stdio",
      "command": "uvx",
      "args": ["codex-as-mcp@latest"]
    }
  }
}

Or use Claude Desktop commands:

claude mcp add codex-subagent -- uvx codex-as-mcp@latest

If you're configuring Codex CLI directly (for example `~/.config/codex/config.toml`), add:

[mcp_servers.subagents]
transport = "stdio"
command = "uvx"
args = ["codex-as-mcp@latest"]
# Increase if you see ~60s tool-call timeouts when running longer Codex tasks.
# tool_timeout_sec = 600

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 165 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # codex-as-mcp
  2. [中文版](./README.zh-CN.md)
  3. `codex-as-mcp` is a small **Model Context Protocol (MCP)** server that lets MCP clients (Claude Code, Cursor, etc.) delegate work to the **Codex CLI**.
  4. It exposes two tools that run Codex in the server's current working directory:
  5. - `spawn_agent(prompt: str)`
  6. - `spawn_agents_parallel(agents: list[dict])`
  7. Under the hood, each agent runs something like:
  8. `codex exec --cd <server cwd> --skip-git-repo-check --dangerously-bypass-approvals-and-sandbox -`.
  9. The prompt is sent through stdin and then closed. This avoids command-line quoting/length issues and prevents Codex from accidentally reading from the MCP server's JSON-RPC stdin pipe.
  10. Note: `--dangerously-bypass-approvals-and-sandbox` disables sandboxing and confirmation prompts. Use this server only in repos you trust.
  11. ## Use it in Claude Code
  12. There are two tools in codex-as-mcp
  13. ![tools](assets/tools.png)
  14. You can spawn parallel codex subagents using prompt.
  15. ![alt text](assets/claude.png)
  16. Here's a sample Codex session delegating two tasks in parallel.
  17. ![Codex use case](assets/codex.png)
  18. ## Quick start
  19. ### 1. Install Codex CLI
  20. **Requires Codex CLI >= 0.46.0**
  21. ```bash
  22. npm install -g @openai/codex@latest
  23. codex login
  24. # Verify installation
  25. codex --version
  26. ```
  27. Make sure Codex CLI can run non-interactively on your machine (provider + credentials in `~/.codex/config.toml`, or via the provider-specific env var it references).
  28. #### Example: third-party provider + `env_key`
  29. If you're using a third-party provider, configure it in Codex `config.toml` and point `model_provider` at it. When a provider uses `env_key`, Codex CLI expects that env var to be present when it runs.
  30. Example:
  31. ```toml
  32. model_provider = "custom_provider"
  33. [model_providers.custom_provider]
  34. name = "custom_provider"
  35. base_url = "https://..."
  36. wire_api = "responses"
  37. env_key = "PROVIDER_API_KEY"
  38. show_raw_agent_reasoning = true
  39. ```
  40. When using `codex-as-mcp`, make sure the MCP server process has that env var set, so it can pass it through to the spawned `codex` process. The env var name **must match** the `env_key` value above (here: `PROVIDER_API_KEY`).
  41. **Option A (recommended): set env in your MCP client config (if supported)**
  42. ```json
  43. {
  44. "mcpServers": {
  45. "codex-subagent": {
  46. "type": "stdio",
  47. "command": "uvx",
  48. "args": ["codex-as-mcp@latest"],
  49. "env": {
  50. "PROVIDER_API_KEY": "KEY_VALUE"
  51. }
  52. }
  53. }
  54. }
  55. ```
  56. **Option B: pass env via server args**
  57. ```bash
  58. uvx codex-as-mcp@latest --env PROVIDER_API_KEY=KEY_VALUE
  59. ```
  60. **Option C: add via Codex CLI (`codex mcp add`)**
  61. ```bash
  62. codex mcp add codex-subagent --env PROVIDER_API_KEY=KEY_VALUE -- uvx codex-as-mcp@latest
  63. ```
  64. Security note: passing secrets via command-line args may be visible via process lists on your machine; prefer option A when possible.
  65. ### 2. Configure MCP
  66. Add to your `.mcp.json`:
  67. ```json
  68. {
  69. "mcpServers": {
  70. "codex-subagent": {
  71. "type": "stdio",
  72. "command": "uvx",
  73. "args": ["codex-as-mcp@latest"]
  74. }
  75. }
  76. }
  77. ```
  78. Or use Claude Desktop commands:
  79. ```bash
  80. claude mcp add codex-subagent -- uvx codex-as-mcp@latest
  81. ```
  82. If you're configuring Codex CLI directly (for example `~/.config/codex/config.toml`), add:
  83. ```toml
  84. [mcp_servers.subagents]
  85. transport = "stdio"
  86. command = "uvx"
  87. args = ["codex-as-mcp@latest"]
  88. # Increase if you see ~60s tool-call timeouts when running longer Codex tasks.
  89. # tool_timeout_sec = 600
  90. ```
  91. ## Tools
  92. - `spawn_agent(prompt: str)` – Spawns an autonomous Codex subagent using the server's working directory and returns the agent's final message.
  93. - `spawn_agents_parallel(agents: list[dict])` – Spawns multiple Codex subagents in parallel; each item must include a `prompt` key and results include either an `output` or an `error` per agent.
  94. ## Maintainer live smoke test
  95. The default CI uses unit tests and a fake subprocess path so it can run safely without credentials. Maintainers can additionally run the manually triggered **Live Codex smoke** GitHub Actions workflow with a real provider by setting repository secret `CODEX_LIVE_API_KEY` and providing a Responses-compatible `base_url`/`model` in the workflow inputs.
  96. Note: current Codex CLI rejects `wire_api = "chat"`; chat-completions-only providers such as direct DeepSeek API need either native Codex support for that wire API or a Responses-compatible proxy.
  97. ## Troubleshooting
  98. ### `spawn_agent` times out after ~60s
  99. If you see an error like:
  100. ```text
  101. tool call failed for `subagents/spawn_agent`
  102. timed out awaiting tools/call after 60s
  103. deadline has elapsed
  104. ```
  105. This is typically a client-side MCP tool-call timeout. `spawn_agent` does not return until the spawned `codex exec` process finishes, which can take longer than 60 seconds.
  106. Fix: increase the tool-call timeout in your MCP client.
  107. #### Codex CLI
  108. In your Codex config (`~/.codex/config.toml` or `~/.config/codex/config.toml`), set a higher `tool_timeout_sec` for the MCP server:
  109. ```toml
  110. [mcp_servers.subagents]
  111. transport = "stdio"
  112. command = "uvx"
  113. args = ["codex-as-mcp@latest"]
  114. tool_timeout_sec = 600
  115. ```
  116. #### MCP Inspector / `mcp dev`
  117. If you're testing locally with the MCP Inspector, increase request timeouts (or run `./test.sh`, which exports these):
  118. ```bash
  119. export MCP_SERVER_REQUEST_TIMEOUT=300000
  120. export MCP_REQUEST_TIMEOUT_RESET_ON_PROGRESS=true
  121. export MCP_REQUEST_MAX_TOTAL_TIMEOUT=28800000
  122. ```

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.