This document describes how Codex synchronizes sandbox execution state with Model Context Protocol (MCP) servers through a custom protocol extension. When Codex enforces sandbox restrictions (read-only access, workspace boundaries, specific sandboxing mechanisms), MCP servers require awareness of these constraints to adapt their tool behavior.
This page covers the codex/sandbox-state/update notification, capability checking, and the propagation of state from the app-server and codex-core to external MCP servers.
Sources: codex-rs/codex-mcp/src/mcp/mod.rs86-105 codex-rs/core/src/mcp_tool_call.rs110-118
Sandbox state synchronization is a Codex-specific extension to MCP that enables servers to receive notifications about the active execution environment. This allows external tool servers to:
Restricted, Unrestricted).codex-linux-sandbox).The synchronization utilizes a custom MCP capability (codex/sandbox-state-meta) and metadata injection into tool calls to propagate state from the core agent to external servers.
Sources: codex-rs/codex-mcp/src/rmcp_client.rs75-77 codex-rs/core/src/mcp_tool_call.rs142-146
The synchronization flow originates in the core agent's session management, influenced by the current TurnContext and PermissionProfile, and is delivered to servers via the McpConnectionSet.
The following diagram maps the Natural Language concept of "State Sync" to specific code entities and data flows.
Title: Sandbox State Propagation
Sources: codex-rs/core/src/mcp_tool_call.rs110-152 codex-rs/codex-mcp/src/mcp/mod.rs119-167 codex-rs/codex-mcp/src/connection_manager.rs144-154
The SandboxState represents the snapshot of security constraints applied to a specific tool execution or session context.
The McpConfig struct captures long-lived configuration used to derive sandbox states and determine how servers are launched.
| Field | Code Entity | Description |
|---|---|---|
approval_policy | AskForApproval | Controls if tools require explicit user confirmation. codex-rs/codex-mcp/src/mcp/mod.rs137 |
codex_linux_sandbox_exe | Option<PathBuf> | Path to the Linux sandbox helper binary. codex-rs/codex-mcp/src/mcp/mod.rs147 |
use_legacy_landlock | bool | Toggles legacy Landlock behavior in the sandbox state. codex-rs/codex-mcp/src/mcp/mod.rs149 |
apps_enabled | bool | Whether the built-in app MCP integration is active. codex-rs/codex-mcp/src/mcp/mod.rs154 |
prefix_mcp_tool_names | bool | Whether to prefix tool names with mcp__. codex-rs/codex-mcp/src/mcp/mod.rs157 |
Sources: codex-rs/codex-mcp/src/mcp/mod.rs119-167 codex-rs/codex-mcp/src/lib.rs16
Codex determines if a sandbox state allows for "auto-approval" of tool permissions using the mcp_permission_prompt_is_auto_approved function. This logic checks:
tool_approval_mode is explicitly set to AppToolApproval::Approve. codex-rs/codex-mcp/src/mcp/mod.rs91-93AskForApproval policy is Never. codex-rs/codex-mcp/src/mcp/mod.rs95-97PermissionProfile (specifically Managed) has full disk write access via its sandbox_policy. codex-rs/codex-mcp/src/mcp/mod.rs99-104Sources: codex-rs/codex-mcp/src/mcp/mod.rs86-105
When the model invokes an MCP tool, handle_mcp_tool_call performs a metadata lookup and applies sandbox policies before dispatching the request.
Title: MCP Tool Invocation Data Flow
Sources: codex-rs/core/src/mcp_tool_call.rs110-161 codex-rs/codex-mcp/src/mcp/mod.rs86-105
Servers advertise support for the codex/sandbox-state-meta capability during the MCP initialize handshake. Codex defines this constant as MCP_SANDBOX_STATE_META_CAPABILITY codex-rs/codex-mcp/src/rmcp_client.rs77 Codex tracks this via ManagedClient, which identifies if the server_supports_sandbox_state_meta_capability is true during connection setup codex-rs/codex-mcp/src/rmcp_client.rs109
The Session manages dynamic updates to the MCP runtime via refresh_mcp_if_dirty codex-rs/core/src/session/mcp.rs135-140 If configuration or auth changes, the McpConnectionSet is re-initialized codex-rs/codex-mcp/src/connection_manager.rs164-182 This ensures that the SandboxState propagated to tools reflects the most recent permission profile and available capability roots codex-rs/core/src/session/mcp.rs165-172
To maintain sandbox integrity, Codex uses rewrite_mcp_tool_arguments_for_openai_files to ensure that tool arguments containing file paths are correctly translated when interacting with OpenAI-compatible file stores codex-rs/core/src/mcp_tool_call.rs14
Sources: codex-rs/core/src/session/mcp.rs83-172 codex-rs/codex-mcp/src/rmcp_client.rs75-77 codex-rs/core/src/mcp_tool_call.rs14
| Entity | Location | Role |
|---|---|---|
handle_mcp_tool_call | codex-rs/core/src/mcp_tool_call.rs110-118 | Orchestrates MCP tool execution, including approval and sandbox checks. |
AppToolPolicyEvaluator | codex-rs/core/src/mcp_tool_call.rs30 | Evaluates whether an app-tool call is allowed under current policy. |
McpConnectionSet | codex-rs/codex-mcp/src/connection_manager.rs144-154 | Manages lifecycles and capability negotiation for all MCP servers. |
McpConfig | codex-rs/codex-mcp/src/mcp/mod.rs119 | Holds runtime settings for MCP, including sandbox executor paths. |
SandboxState | codex-rs/codex-mcp/src/lib.rs16 | Struct defining the state schema sent to servers. |
refresh_mcp_if_dirty | codex-rs/core/src/session/mcp.rs135 | Ensures the MCP runtime is synchronized with the current session state. |
If an MCP tool call fails due to parsing or server availability, Codex returns a CallToolResult::from_error_text codex-rs/core/src/mcp_tool_call.rs130 and emits a McpToolCallError to the session history codex-rs/core/src/mcp_tool_call.rs43
Sources: codex-rs/core/src/mcp_tool_call.rs110-135 codex-rs/core/src/session/mcp.rs135-172 codex-rs/codex-mcp/src/connection_manager.rs144-154
Refresh this wiki
This wiki was recently refreshed. Please wait 5 days to refresh again.