OpenAI Codex MCP Documentation: CLI Guide

OpenAI Codex MCP Documentation: CLI Guide

The OpenAI Codex CLI provides command-line artificial intelligence assistance for software engineering workflows, including autonomous test execution, code refactoring, and multi-file debugging. By natively integrating the Model Context Protocol (MCP), the Codex CLI connects language model reasoning directly to local databases, git version control, external cloud APIs, and specialized development tools.

Unlike graphical desktop hosts that rely on background electron processes, the Codex CLI operates inside terminal sessions and continuous integration runners. This requires a dedicated approach to subprocess management, standard input and output stream isolation, and configuration schemas.

This guide provides an authoritative technical reference for the OpenAI Codex CLI Model Context Protocol integration, detailing the config.toml specification, command-line operations, JSON-RPC message flows, and troubleshooting procedures.

1. Protocol Architecture and Subprocess Mechanics

When the OpenAI Codex CLI initializes, it parses server definitions declared in its global configuration file. For each enabled server, the Codex runtime spawns an independent child process communicating over Standard Input and Output (stdio).

Subprocess Lifecycle and Isolation Rules

1. ▸Strict Stdio Stream Hygiene: The Codex CLI uses standard input (stdin) to deliver JSON-RPC requests and standard output (stdout) to receive JSON-RPC responses. Any diagnostic printing, status logging, or interactive confirmation prompt directed to standard output corrupts the framing buffer and breaks the connection.
2. ▸Standard Error Routing: Diagnostic messages from child processes are captured from standard error (stderr) and forwarded to the internal Codex logging subsystem.
3. ▸Graceful Signal Handling: When a terminal user terminates Codex (via SIGINT or Ctrl+C), the CLI runtime sends SIGTERM signals to all active child MCP server processes to prevent orphaned background tasks.

2. Environment Prerequisites and Installation

The Codex CLI can invoke MCP servers authored in TypeScript (via Node.js and npx), Python (via uvx and python), or compiled system binaries. Ensure the following prerequisites are installed on your host system:

Verify your active Codex CLI installation:

codex --version

Configuration files reside in the user home directory:

• ▸macOS / Linux: ~/.codex/config.toml
• ▸Windows PowerShell: $HOME\.codex\config.toml (or %USERPROFILE%\.codex\config.toml)

3. Configuration Specification (config.toml)

Codex CLI stores MCP registrations in TOML format under the [mcp_servers.<name>] table.

Schema Fields Reference

Complete config.toml Example

# ~/.codex/config.toml

# 1. GitHub Integration (Node.js via npx)
[mcp_servers.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]

[mcp_servers.github.env]
GITHUB_PERSONAL_ACCESS_TOKEN = "ghp_your_personal_access_token_here"

# 2. Local PostgreSQL Database Connection
[mcp_servers.postgres]
command = "npx"
args = [
  "-y",
  "@modelcontextprotocol/server-postgres",
  "postgresql://appuser:secretpassword@/production_analytics"
]

# 3. SQLite Database (Python via fast uvx runner)
[mcp_servers.sqlite]
command = "uvx"
args = ["mcp-server-sqlite", "--db-path", "./data/analytics.db"]

# 4. Brave Search Integration
[mcp_servers.brave_search]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-brave-search"]

[mcp_servers.brave_search.env]
BRAVE_API_KEY = "BSA_your_brave_api_key_here"

4. Command-Line Interface Reference

The Codex CLI provides a dedicated codex mcp subcommand suite for managing registered servers without manually editing TOML files.

1. codex mcp list

Displays all configured servers, transport modes, connection statuses, and tool counts:

codex mcp list

Example Terminal Output:

SERVER NAME       TRANSPORT   STATUS       TOOLS   RESOURCES
github            stdio       Connected    7       0
postgres          stdio       Connected    1       2
sqlite            stdio       Connected    2       1
brave_search      stdio       Connected    2       0

2. codex mcp add

Appends a new server definition to config.toml:

codex mcp add --name fetch --command "uvx" --args "mcp-server-fetch"

To include environment variables:

codex mcp add --name slack --command "npx -y @modelcontextprotocol/server-slack" --env SLACK_BOT_TOKEN=xoxb-xxx

3. codex mcp tools <server_name>

Inspects tool schemas, input parameters, and descriptions registered by an active server:

codex mcp tools postgres

4. codex mcp restart <server_name>

Restarts a crashed server or reloads after updating environment secrets without terminating your active Codex session:

codex mcp restart github

5. codex mcp logs <server_name>

Streams the standard error (stderr) diagnostic log of a specific child process:

codex mcp logs postgres

5. JSON-RPC 2.0 Protocol Message Traces

During interactive execution, Codex exchanges JSON-RPC 2.0 messages with its child processes. The following frames demonstrate a standard lifecycle trace.

Client Initialization (initialize)

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {
      "roots": { "listChanged": true },
      "sampling": {}
    },
    "clientInfo": {
      "name": "openai-codex-cli",
      "version": "0.14.2"
    }
  }
}

Tool Discovery (tools/list)

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list",
  "params": {}
}

Tool Execution Request (tools/call)

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "read_query",
    "arguments": {
      "query": "SELECT COUNT(*) FROM users WHERE is_active = true;"
    }
  }
}

6. Common Errors and Production Troubleshooting

When operating MCP servers within the OpenAI Codex CLI, engineers commonly encounter the following operational issues:

Error: spawn npx ENOENT

• ▸Symptom: Codex logs indicate child process creation failure immediately upon launch.
• ▸Root Cause: The terminal environment executing Codex does not possess npx in its default PATH, common when invoking Codex from non-login shells or desktop shortcuts.
• ▸Resolution: Provide the absolute path to the executable binary in config.toml:
  • ▸macOS / Linux: command = "/opt/homebrew/bin/npx" or command = "/usr/local/bin/npx"
  • ▸Windows PowerShell: command = "C:\\Program Files\\nodejs\\npx.cmd"

Error: Silent Process Stall (Hanging on Startup)

• ▸Symptom: Codex displays "Connecting..." indefinitely and fails to discover registered tools.
• ▸Root Cause: The command invoked prompted the user for terminal input (e.g. npx asking "Need to install the following packages: ok to proceed? (y)"). Because standard input is bound to the JSON-RPC channel, the process hangs awaiting user keystrokes.
• ▸Resolution: Always pass the non-interactive automatic approval flag -y when invoking npx:

args = ["-y", "@modelcontextprotocol/server-github"]

Error: Unicode Decode Error on Windows (CP1252 vs UTF-8)

• ▸Symptom: Python servers fail on Windows with UnicodeDecodeError: 'charmap' codec can't decode byte.
• ▸Resolution: Force Python to use UTF-8 encoding for standard streams by adding PYTHONUTF8 = "1" to the server environment table:

[mcp_servers.python_server.env]
PYTHONUTF8 = "1"

7. External Citations and Security Guardrails

Running terminal-level coding agents with external tool integrations requires strict security boundaries:

• ▸Least-Privilege Database Access: Connect database servers using dedicated read-only credentials. Never provide administrative or DROP TABLE permissions to interactive coding assistants.
• ▸Token Storage: Keep personal access tokens out of shared source repositories. Store tokens in local environment variables and reference them securely.
• ▸Official Specifications and Repositories:
  • ▸Model Context Protocol Specification (opens in a new tab)
  • ▸Official Model Context Protocol GitHub Organization (opens in a new tab)
  • ▸Official TypeScript SDK on npm (opens in a new tab)