Registry / llm-agents / mcp-codex-worker

mcp-codex-worker

library1.0.34jsnpmunverified

The `mcp-codex-worker` package provides a stdio MCP server that acts as a bridge between MCP clients and the Codex app-server runtime. It offers a set of five specialized task tools (`spawn-task`, `wait-task`, `respond-task`, `message-task`, `cancel-task`) designed for orchestrating fully autonomous AI agents. A key differentiator is its automatic approval mechanism for all Codex commands, file changes, elicitation requests, and permission requests, enabling unassisted task execution. The worker delegates all direct OpenAI API interactions to the `codex app-server` and exclusively supports `gpt-5.4` models, allowing users to specify reasoning levels like `medium` or `xhigh`. It provides comprehensive observability through file-backed reporting (including `meta.json`, `summary.log`, `verbose.log`, `events.jsonl`) and MCP resource subscriptions. The current stable version is `1.0.34`.

llm-agents ai-ml workflow observability

npm install mcp-codex-worker

github ↗package ↗

INSTALL

IMPORT

SIG · MCP-CODEX-WORKER

mcp-codex-worker

llm-agentsjavascriptv1.0.34

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Demonstrates how to install the `mcp-codex-worker` using `npx` and integrate it as an MCP server within a Claude Code environment, including how an agent would hypothetically invoke its task tools.

{ "mcpServers": { "codex-worker": { "command": "npx", "args": [ "-y", "mcp-codex-worker@latest" ], "env": { "CODEX_LB_API_KEY": "${CODEX_LB_API_KEY}" } } } } // To launch an agent task: // const spawnResult = await agent.tools['spawn-task']({ // prompt: "Write a NodeJS script that fetches data from an API and saves it to a file.", // reasoning: "gpt-5.4(medium)" // }); // console.log(`Task spawned: ${spawnResult.task_id}`); // // To wait for the task to complete: // const waitResult = await agent.tools['wait-task']({ task_id: spawnResult.task_id }); // console.log(`Task ${spawnResult.task_id} completed with status: ${waitResult.status}`); // if (waitResult.output) { // console.log('Task output:', waitResult.output); // }

mcp-codex-worker --version

Debug

Known issues

breakingThe `mcp-codex-worker` strictly requires Node.js version 22 or higher. Running it with older Node.js versions will result in execution failures and prevent the server from starting.

fix

Upgrade your Node.js environment to version 22.0.0 or later using a tool like nvm (Node Version Manager) or by updating your system's Node.js installation.

affects: >=1.0.0

gotchaThis worker automatically approves ALL Codex command requests, file changes, elicitation, and permission requests without user intervention. This behavior is intended for fully autonomous agents and should be used with extreme caution in untrusted or production environments, as it grants full access within its sandbox.

fix

Understand the security implications and only use this worker in secure, isolated environments where full autonomy and auto-approval are desired. Be aware that only `user_input` and `dynamic_tool` requests will pause the task.

affects: >=1.0.0

gotchaThe worker requires either `CODEX_LB_API_KEY` or `OPENAI_API_KEY` to be set in its environment for delegated `codex app-server` operations. Failure to provide one will prevent tasks from executing and result in errors.

fix

Ensure `CODEX_LB_API_KEY` or `OPENAI_API_KEY` is correctly configured in the environment variables passed to the worker process (e.g., in the `env` block of your `mcpServers` configuration for Claude Code).

affects: >=1.0.0

gotchaOnly the `gpt-5.4` model is supported for agent reasoning, with specific sub-options (`medium`, `high`, `xhigh`, `low`). Attempts to use other models or unsupported `reasoning` parameters will fail or lead to undefined behavior.

fix

Ensure your agent explicitly requests `gpt-5.4` and one of the specified `reasoning` parameters (e.g., `gpt-5.4(medium)`) when invoking `spawn-task`.

affects: >=1.0.0

Errors

Common errors & fixes

Error: Node.js version detected as X.Y.Z. This worker requires Node.js >= 22.0.0.

The system's active Node.js version is older than the minimum requirement for the `mcp-codex-worker`.

fix

Upgrade your Node.js environment to version 22 or later. For example, using nvm: `nvm install 22 && nvm use 22`.

Error: Missing required environment variable: CODEX_LB_API_KEY (or OPENAI_API_KEY)

Neither `CODEX_LB_API_KEY` nor `OPENAI_API_KEY` was found in the worker's environment variables, which are essential for its operation.

fix

Set one of the required API keys. For Claude Code configuration, ensure it's defined in the `env` block: `"env": { "CODEX_LB_API_KEY": "${CODEX_LB_API_KEY}" }`.

Task 'bold-eagle-456' paused: awaiting approval for command 'npm test'

This error indicates a misunderstanding or misconfiguration, as the `mcp-codex-worker` automatically approves all command, file change, elicitation, and permission requests.

fix

This specific error should not occur with `mcp-codex-worker` if configured correctly. If it does, check the worker's verbose logs (`~/.mcp-codex-worker/tasks/<task-id>/verbose.log`) for unexpected behavior or conflicts, or verify the worker is correctly configured and running within its expected environment.

Invalid model or reasoning parameter specified: gpt-4-turbo

The worker only supports the `gpt-5.4` model and its specific `reasoning` sub-parameters.

fix

Modify your agent's task spawning logic to explicitly request `gpt-5.4` and one of its supported `reasoning` values (e.g., `gpt-5.4(medium)` or `gpt-5.4(high)`).

Upgrade

Version history

1.0.34latest on npm

Audit

Dependencies

codexrequiredRequires the 'codex' CLI to be installed and available in the system PATH for delegating work.

Agent activity

14 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/yigitkonur/mcp-codex-worker ↗

packagehttps://www.npmjs.com/package/mcp-codex-worker ↗