Codex MCP Reference Docs

This document serves as the complete reference for integrating the Model Context Protocol (MCP) with the OpenAI Codex CLI. It covers configuration schemas, command-line usage, and common troubleshooting steps.

Configuration Schema (config.toml)

The Codex CLI uses a TOML file for configuration. The MCP settings are nested under the mcpServers table.

Server Definition

Each server is defined as a sub-table of mcpServers (e.g., [mcpServers.my_server]).

Example Schema

[mcpServers.example]
command = "node"
args = ["/path/to/server.js", "--verbose"]

  [mcpServers.example.env]
  API_KEY = "your_secret_key"
  PORT = "8080"

Command Line Interface

The Codex CLI provides several commands for managing and interacting with your MCP servers.

codex mcp list

Lists all configured MCP servers and their current connection status.

Example Output:

SERVER NAME       STATUS       TOOLS AVAILABLE
filesystem        Connected    5
github            Failed       0
sqlite            Connected    2

codex mcp restart <server_name>

Restarts a specific MCP server. This is useful if a server crashes or if you have updated its configuration.

Example:

codex mcp restart filesystem

codex mcp logs <server_name>

Tails the standard error (stderr) output of a specific MCP server, which is essential for debugging server-side issues.

Example:

codex mcp logs github

Troubleshooting

Connection Refused / Server Failed to Start

Symptoms: codex mcp list shows a Failed status for a server.

Solutions:

1. ▸Check the executable: Ensure the command (e.g., npx, uvx) is installed and available in your system's PATH.
2. ▸Review the logs: Run codex mcp logs <server_name> to see why the process crashed. Common reasons include missing dependencies or incorrect arguments.
3. ▸Verify Node/Python versions: Some servers require specific versions of Node.js (e.g., v18+) or Python (e.g., 3.10+).

Missing Environment Variables

Symptoms: The server connects, but tool executions fail with authentication errors.

Solutions:

1. ▸Ensure your API keys are correctly defined in the [mcpServers.<name>.env] section.
2. ▸Remember that TOML tables must be defined in order. The env sub-table must appear after the main server properties.

Tools Not Appearing

Symptoms: The server connects, but Codex says it doesn't have access to the expected tools.

Solutions:

1. ▸Verify that the server implementation correctly handles the tools/list JSON-RPC method.
2. ▸Try restarting the server using codex mcp restart <name> to force the Codex CLI to re-fetch the tool list.