Module mcp 

Launch and interact with Codex MCP + app servers using stored runtime definitions.

• Spawn codex mcp-server, call codex/codex or codex/codex-reply, and stream codex/event notifications (task completion, approvals, cancellations, errors).
• Start codex app-server threads/turns and surface item/task_complete notifications.
• Manage [mcp_servers] and [app_runtimes] config entries, resolve them into launch-ready runtimes, and expose read-only APIs (including pooled app runtimes) without mutating stored config or thread metadata.
• Requests may be cancelled via the JSON-RPC $ /cancelRequest flow.

The MCP server exposes two tool entrypoints:

• codex/codex: start a new Codex session with a prompt.
• codex/codex-reply: continue an existing session by conversation ID.

The app-server supports thread/start, thread/resume, turn/start, and turn/interrupt requests. Runtime and pool helpers keep resume hints/metadata intact while starting, reusing, and stopping app-server instances.

Structs

AddAppRuntimeRequest

Input for adding or updating an app runtime entry.

AddServerRequest

Input for adding or updating an MCP server entry.

AppCallHandle

Handle returned for each app-server call, bundling response and notifications.

AppRuntime

Stored app runtime converted into launch-ready config with metadata intact.

AppRuntimeApi

Read-only helpers around AppRuntimeManager backed by stored config.

AppRuntimeDefinition

Stored definition for launching an app-server runtime.

AppRuntimeEntry

App runtime definition coupled with its name.

AppRuntimeHandle

Prepared app runtime with merged stdio config and metadata.

AppRuntimeLauncher

Launch-ready stdio config bundled with app metadata.

AppRuntimeManager

Non-destructive manager for app runtimes backed by launch-ready configs.

AppRuntimePool

Async pool that starts, reuses, and stops app runtimes without mutating config.

AppRuntimePoolApi

Public API around AppRuntimePool that exposes pooled lifecycle helpers.

AppRuntimeSummary

Summarized app runtime metadata for listing.

ApprovalRequest

Approval request emitted as part of a codex/event notification.

ClientInfo

Client metadata attached to the initialize request.

CodexAppServer

Client wrapper around the stdio app-server.

CodexCallHandle

Handle returned for each codex call, bundling response and notifications.

CodexCallParams

Parameters for codex/codex (new session).

CodexCallResult

Final response payload for codex/codex or codex/codex-reply.

CodexMcpServer

Client wrapper around the stdio MCP server.

CodexReplyParams

Parameters for codex/codex-reply (continue an existing conversation).

ForkedThread

Forked thread metadata returned by thread/fork.

InitializeParams

Parameters for the initial initialize handshake.

ManagedAppRuntime

Running app-server instance with metadata preserved.

ManagedHttpRuntime

HTTP runtime connector with tool hints preserved.

ManagedStdioRuntime

Running stdio MCP server along with its pipes.

McpConfigManager

Helper to load and mutate MCP + app runtime config stored under [mcp_servers] and [app_runtimes].

McpLoginResult

Result of logging into a server (auth token set in env var).

McpLogoutResult

Result of clearing a stored auth token.

McpRuntimeApi

Read-only helpers around McpRuntimeManager backed by stored config.

McpRuntimeManager

Lightweight runtime manager that owns resolved launchers/connectors.

McpRuntimeServer

Resolved runtime configuration for an MCP server, ready for spawning or connecting.

McpRuntimeSummary

Summarized runtime metadata for listing available MCP servers.

McpServerDefinition

JSON-serializable MCP server configuration stored under [mcp_servers].

McpServerEntry

MCP server definition coupled with its name.

McpServerLauncher

Launcher/connector wrapper around a resolved MCP runtime server.

McpToolConfig

Tool allow/deny lists for a given MCP server.

ResolvedStreamableHttpDefinition

HTTP runtime config with bearer tokens resolved from the environment.

StdioLauncher

Prepared stdio launcher with merged env and startup timeout.

StdioServerConfig

Shared launch configuration for stdio MCP/app-server processes.

StdioServerDefinition

Stdio transport configuration for an MCP server.

StreamableHttpConnector

Prepared HTTP connector with resolved headers and timeouts.

StreamableHttpDefinition

HTTP transport configuration that supports streaming responses.

ThreadForkParams

Parameters for thread/fork.

ThreadForkResponse

Response payload for thread/fork.

ThreadListParams

Parameters for thread/list.

ThreadListResponse

Response payload for thread/list.

ThreadResumeParams

Parameters for thread/resume.

ThreadStartParams

Parameters for thread/start.

ThreadSummary

Thread metadata summary returned by thread/list.

TurnInput

TurnInterruptParams

Parameters for turn/interrupt.

TurnStartParams

Parameters for turn/start.

TurnStartParamsV2

Parameters for turn/start (fork-focused pinned v2 subset).

Enums

AppNotification

Notification emitted by the app-server.

AppRuntimeError

Errors surfaced while reading app runtimes.

ApprovalDecision

Decision payload sent back to the MCP server in response to an approval prompt.

ApprovalKind

Classification for approval prompts surfaced by the MCP server.

CodexEvent

Notification emitted by codex/event.

McpConfigError

Errors surfaced while managing MCP config entries.

McpError

Errors surfaced while managing MCP/app-server transports.

McpRuntimeError

Errors surfaced while starting or stopping MCP runtimes.

McpRuntimeHandle

Handle returned by McpRuntimeManager::prepare for either transport.

McpRuntimeSummaryTransport

Transport kind used by a runtime.

McpRuntimeTransport

Transport-specific runtime configuration.

McpServerLauncherTransport

Transport-specific launcher/connector.

McpTransport

Supported transport definitions for MCP servers.

ThreadListSortKey

Sorting key for thread/list.

UserInputV2

User input shape pinned for fork flows.

Constants

DEFAULT_CONFIG_FILE

Default config filename placed under CODEX_HOME.

METHOD_CANCEL

JSON-RPC cancellation method per the spec.

METHOD_CODEX

Tool-call method exposed by the MCP server.

METHOD_CODEX_APPROVAL

Expected approval response hook (server-specific; confirmed during E2).

METHOD_CODEX_EVENT

Notification channel emitted by codex mcp-server.

METHOD_CODEX_REPLY

Tool-call method for follow-up prompts (codex-reply).

METHOD_EXIT

JSON-RPC method name used after shutdown to signal exit.

METHOD_INITIALIZE

JSON-RPC method name used to initialize MCP servers.

METHOD_SHUTDOWN

JSON-RPC method name used to shut down MCP servers.

METHOD_THREAD_FORK

Fork an existing thread.

METHOD_THREAD_LIST

List threads (paged).

METHOD_THREAD_RESUME

Resume an existing thread.

METHOD_THREAD_START

Method names exposed by codex app-server.

METHOD_TURN_INTERRUPT

Interrupt an active turn.

METHOD_TURN_START

Start a new turn on a thread.

Type Aliases

EventStream

Stream of notifications surfaced alongside a JSON-RPC response.

RequestId

Unique identifier for JSON-RPC calls.