How to add the Sandbox MCP server to Codex

Adding the Sandbox MCP server registers a local stdio launcher in Codex so a session can open the existing shell, network-tools, or ubuntu-shell sandboxes through the local sandbox-mcp runtime. This is the right path when sandbox-mcp is already installed on the host and the sandbox catalog already exists.

Current OpenAI Codex docs say user-level MCP configuration lives in ~/.codex/config.toml, with optional project-scoped .codex/config.toml layers in trusted repositories, and codex mcp add <server-name> -- <stdio server-command> is the supported CLI path for saving a local MCP launcher.

Current local verification shows sandbox-mcp starts with --stdio and that hosts using the common ~/.config/sandbox-mcp layout need XDG_CONFIG_HOME=$HOME/.config forwarded into the saved launcher. Without that environment variable on this macOS host, sandbox-mcp fell back to ~/Library/Application Support/sandbox-mcp instead of the existing sandbox catalog.

1. Add the saved sandbox-mcp launcher with the same config root that stores the sandbox definitions.

   $ codex mcp add sandbox-mcp --env XDG_CONFIG_HOME=$HOME/.config -- $HOME/.local/bin/sandbox-mcp --stdio
   Added global MCP server 'sandbox-mcp'.

   Replace $HOME/.local/bin/sandbox-mcp if the binary is installed elsewhere. If the sandbox catalog already uses the platform default location, keep the same --stdio launcher and omit the --env XDG_CONFIG_HOME=$HOME/.config portion.

   This command only saves the launcher in Codex. It does not pull sandbox definitions or build the underlying Docker images.

2. Retrieve the saved entry in JSON and confirm that Codex stored a local stdio transport with the expected command and environment.

   $ codex mcp get sandbox-mcp --json
   {
     "name": "sandbox-mcp",
     "enabled": true,
     "disabled_reason": null,
     "transport": {
       "type": "stdio",
       "command": "/Users/username/.local/bin/sandbox-mcp",
       "args": [
         "--stdio"
       ],
       "env": {
         "XDG_CONFIG_HOME": "/Users/username/.config"
       },
       "env_vars": [],
       "cwd": null
     },
     "enabled_tools": null,
     "disabled_tools": null,
     "startup_timeout_sec": null,
     "tool_timeout_sec": null
   }

   The success state for this page is transport.type = stdio, transport.command pointing to the sandbox-mcp binary, and transport.env.XDG_CONFIG_HOME matching the config root that contains the sandbox catalog.

3. Start Codex and confirm the saved server appears in the MCP panel for the current session.

   $ codex

   Current OpenAI Codex docs say /mcp in the TUI shows the active MCP servers for the session. If sandbox-mcp is listed there, Codex can attempt the sandbox tools during the run.