Codex App MCP server
Commit Nov 15, 2026Enables MCP clients to use Codex as a collaborating agent by starting and continuing threads through the official Codex SDK.
Also known as PyYoshi/codex-app-mcp
- Stars
- 0
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 15, 2026
- License
- MIT
What is Codex App MCP?
Codex App enables MCP clients to use Codex as a collaborating agent by starting and continuing threads through the official Codex SDK.
Summary generated from the project's README
About Codex App MCP server
Integrating Codex as a collaborating agent into MCP clients like OpenCode or Claude Code is what this local stdio server enables. It provides a bridge that allows developers to start and continue conversation threads using the official Codex SDK without needing to reimplement the runtime. The server operates through two primary tools, codex and codex-reply, which manage thread creation and subsequent interactions via thread IDs.
Setup requires Python 3.15.x, uv, and an existing Codex login stored in your local authentication files. Users must also have network access to OpenAI for inference. The server follows a strict safety model where the default sandbox is read-only and all approval requests are declined. It uses a fail-closed approach, meaning it restricts access to specific workspaces defined in a bridge.toml configuration file to ensure security boundaries are maintained during development tasks.
What you can do with it
- 1Secure workspace integrationYou can restrict the AI agent to specific project directories using allowed roots in a configuration file.
Written from the project's README. Every use case is checked against a quote from it.
Automated checks
Ran Nov 15, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablepyyoshi/codex-app-mcp is public and reachablegithub.com/pyyoshi/codex-app-mcp ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-14github.com/pyyoshi/codex-app-mcp ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubcodex-app-mcp
codex-app-mcp is a local stdio MCP server that exposes Codex App Server
threads through the codex and codex-reply tools. It uses the official
Codex SDK and deliberately implements a small, non-interactive, fail-closed
compatibility surface.
Why this project exists
Codex CLI previously exposed an MCP server mode. After that mode was removed, tools without an official Codex integration—such as OpenCode—no longer had a simple way to use Codex as a collaborating agent. This project restores that workflow as a narrowly scoped bridge built on the supported Codex SDK: any MCP client can start a Codex thread and continue it by thread ID without embedding or reimplementing the Codex runtime.
Safety model
- Approval requests are declined; only
approval-policy=neveris supported. - The default sandbox is
read-only;danger-full-accessis rejected. - One turn may be active per bridge process. Calls are never silently queued.
- A turn whose execution state is unknown is never submitted again automatically.
allowed_rootsrestricts accepted workspaces and is empty (deny all) by default.- Logs go to stderr and omit prompts, answers, credentials, and file contents.
This is not a general-purpose App Server gateway. Interactive approval, steering an active turn, and HTTP transport are outside the v0.1 scope.
Requirements
- Python 3.15.x (the latest stable Python major supported by this release)
- uv
- an existing Codex login, such as
~/.codex/auth.json - network access to OpenAI when running inference
Runtime boundaries are pinned to openai-codex==0.163.0 and mcp==2.3.0.
The Codex runtime bundled with the SDK is used; an unrelated codex on PATH
is not substituted.
Quick start
Create a safe project-local configuration from the target repository:
cd /absolute/path/to/target-project
uvx --from git+https://github.com/PyYoshi/codex-app-mcp.git@v0.1.2 \
codex-app-mcp init
uvx --from git+https://github.com/PyYoshi/codex-app-mcp.git@v0.1.2 \
codex-app-mcp doctor
init creates bridge.toml at the Git root (or current directory) and places
that workspace in allowed_roots. It never overwrites an existing file. A
global config can be created with init --global, although project-local
configuration is recommended. The first uvx run downloads the pinned runtime
and may transfer roughly 120 MiB.
--global changes where the configuration is stored; it does not broaden the
allowed workspace. The current Git root is still selected by default. Use
--root /absolute/path/to/workspace to select another workspace, and edit
allowed_roots afterward when a global configuration must cover several
separate locations. For safety, init refuses filesystem roots and the entire
home directory.
Configuration discovery is bottom-up:
--config PATH, when supplied- the nearest
bridge.toml, searching from the bridge launch directory upward - the user config (
$XDG_CONFIG_HOME/codex-app-mcp/bridge.toml, or the platform equivalent) - built-in fail-closed defaults
A bridge.toml found by the upward search may come from a cloned repository, so
its allowed_roots must stay inside the directory that holds it, and on POSIX
the file must be owned by you and not world-writable. Pass --config PATH to
allow workspaces elsewhere.
Individual values use CLI > CODEX_APP_MCP_* environment > TOML > built-in
precedence. defaults.cwd remains supported for unusual launchers, but normally
the client should launch the bridge in its workspace and leave it unset. See
configuration.
MCP client configuration
Use an executable plus an argument array, not a shell command string. Pin the release tag shown below; use a full commit SHA only when testing unreleased code.
Claude Code
claude mcp add codex -- \
uvx --from git+https://github.com/PyYoshi/codex-app-mcp.git@v0.1.2 \
codex-app-mcp serve
OpenCode
{
"mcp": {
"codex": {
"type": "local",
"command": [
"uvx", "--from",
"git+https://github.com/PyYoshi/codex-app-mcp.git@v0.1.2",
"codex-app-mcp", "serve"
],
"enabled": true
}
}
}
Do not register this bridge in the child Codex runtime's own MCP configuration; that can create recursive self-connection. The bridge includes a guard, but the configuration itself is unsupported.
Tools
Start a thread:
{"prompt":"Summarize this repository.","sandbox":"read-only"}
Continue it with the returned opaque thread ID:
{"prompt":"Now list the main risks.","threadId":"01a0..."}
Successful results expose threadId and content in structuredContent and in
a JSON text fallback for clients that do not surface structured content. Full
input, output, model, effort, cancellation, and error contracts are documented
in docs.
Development
Tools used by this repository are pinned with aqua:
aqua install
aqua exec -- uv sync --frozen --all-groups
aqua exec -- uv run --frozen pytest -m 'not live' -q
aqua exec -- uv run --frozen ruff check src tests
aqua exec -- uv run --frozen ruff format --check src tests
aqua exec -- uv build
aqua exec -- betterleaks dir .
aqua exec -- betterleaks git . --platform github
Live tests perform real authentication, inference, sandboxed file operations, cancellation, and process termination. Run them only with explicit authorization:
aqua exec -- uv run --frozen pytest -m live -q
See CONTRIBUTING.md, SECURITY.md, and the testing guide. This project is distributed under the MIT License and is installed directly from GitHub; it is not published on PyPI.
Codex App MCP questions
What are the safety restrictions for the Codex bridge?
The server uses a fail-closed model where approval requests are declined, the default sandbox is read-only, and workspace access is restricted by allowed_roots.