MCP server

Expose a local Codex engine to another MCP client over stdio.

Table of Contents

Start the server
Protocol lifecycle
Supporting methods

Codex can run as an experimental MCP server. It exposes the local agent engine over standard MCP using JSON-RPC 2.0, line-delimited messages on stdin/stdout. This lets another MCP client start and control Codex threads and turns.

Start the server

codex mcp-server

Inspect it with the official MCP Inspector:

npx @modelcontextprotocol/inspector codex mcp-server

The server inherits the Codex CLI environment and configuration. Keep it attached to a trusted local client: it can operate on the working directory with the permissions available to Codex.

Protocol lifecycle

Initialize once per connection, acknowledge with initialized, then issue requests. New integrations should use the v2 thread and turn methods:

Method	Purpose
`thread/start`	Create a thread and select its working directory and options.
`thread/resume`	Reconnect to a persisted thread.
`thread/fork`	Create a new thread from an existing thread.
`thread/read`	Read thread state and history.
`thread/list`	List persisted threads.
`turn/start`	Submit user input to a thread.
`turn/steer`	Change an in-flight turn.
`turn/interrupt`	Stop an in-flight turn.

The server emits typed notifications such as thread/started and turn/completed, plus codex/event/* notifications for live agent events. Approval requests include applyPatchApproval and execCommandApproval.

Supporting methods

The interface also includes account and configuration methods (account/read, config/read, config/value/write, config/batchWrite), model discovery with model/list, and MCP management methods such as mcpServerStatus/list and mcpServer/tool/call.

Use the exact request and response shapes from the MCP server interface. This interface is experimental and may change without notice.

The Codex CLI is also an MCP client. Configure external servers with codex mcp add or the [mcp_servers] section in ~/.codex/config.toml; see MCP server configuration.

更新于 2026年8月31日