Configure MCP Servers in OpenAI Codex CLI

Configure MCP Servers in Codex CLI

Connecting the OpenAI Codex CLI to external tools, databases, and APIs relies on the Model Context Protocol (MCP). Codex manages server discovery and persistent tool registration through its centralized config.toml manifest, supporting both local child processes (stdio) and remote Server-Sent Events (sse) endpoints.

Prerequisites

• ▸OpenAI Codex CLI (v2.0.0 or higher). Verify with codex --version.
• ▸Node.js 18+ (for npx servers) or Python 3.10+ / uv (for uvx servers).
• ▸Access to an active internet connection or local database instances.

Locating Your config.toml File

The Codex CLI reads its configuration from a centralized config.toml file. Depending on your operating system, locate or create this file in the following default directory:

• ▸Windows: %USERPROFILE%\.codex\config.toml (or %APPDATA%\Codex\config.toml)
• ▸macOS: ~/.codex/config.toml (or ~/Library/Application Support/Codex/config.toml)
• ▸Linux: ~/.codex/config.toml (or ~/.config/codex/config.toml)

Tip: You can inspect your active config file path anytime by running:

bashCopy

codex config path

TOML Configuration Schema

MCP servers in Codex CLI are defined under the [mcp_servers.<name>] table (the legacy [mcpServers.<name>] syntax is also supported for backward compatibility).

Base Structure

[mcp_servers.<server_name>]
command = "executable"
args = ["arg1", "arg2"]

  [mcp_servers.<server_name>.env]
  KEY_NAME = "value"

How to Check Enabled MCP Servers in Codex

To inspect which MCP servers are currently enabled, active, or failing in your Codex CLI session, run:

codex mcp list

Interpreting the Output

SERVER NAME       TRANSPORT   STATUS       TOOLS   RESOURCES
filesystem        stdio       Connected    5       2
github            stdio       Connected    7       0
postgres          stdio       Failed       0       0

• ▸Connected: The MCP handshake (initialize -> initialized) succeeded. Tools are exposed to Codex and ready for autonomous invocation.
• ▸Failed: The process crashed or timed out during handshake. Check logs immediately with codex mcp logs <server_name>.
• ▸Disabled: The server is present in config.toml but toggled off or inactive.

To inspect specific tools exposed by a connected server:

codex mcp tools github

Adding Servers via CLI One-Liners (codex mcp add)

Instead of editing config.toml manually, you can register servers dynamically from your terminal using codex mcp add:

# Add GitHub MCP server with personal access token
codex mcp add --name github --command "npx -y @modelcontextprotocol/server-github" --env GITHUB_PERSONAL_ACCESS_TOKEN=ghp_your_token_here

# Add PostgreSQL MCP server with connection URL
codex mcp add --name postgres --command "npx -y @modelcontextprotocol/server-postgres postgresql://user:pass@/mydb"

# Add Cloudflare MCP server
codex mcp add --name cloudflare --command "npx -y @cloudflare/mcp-server-cloudflare" --env CLOUDFLARE_API_TOKEN=your_token_here

Codex will validate the connection handshake immediately upon addition.

Production Config Recipes

Here are ready-to-copy snippets for the most requested MCP servers in OpenAI Codex CLI:

1. GitHub MCP Server (@modelcontextprotocol/server-github)

Allows Codex to create pull requests, read repository files, search code, and manage issues.

[mcp_servers.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]

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

2. Cloudflare MCP Server (@cloudflare/mcp-server-cloudflare)

Deploy Workers, query D1 databases, manage KV namespaces, and inspect edge logs directly from Codex.

[mcp_servers.cloudflare]
command = "npx"
args = ["-y", "@cloudflare/mcp-server-cloudflare"]

  [mcp_servers.cloudflare.env]
  CLOUDFLARE_API_TOKEN = "cf_token_xxxxxxxxxxxx"
  CLOUDFLARE_ACCOUNT_ID = "account_id_xxxxxxxxxxxx"

3. PostgreSQL MCP Server (@modelcontextprotocol/server-postgres)

Query database schemas, inspect tables, and execute read-only queries safely.

[mcp_servers.postgres]
command = "npx"
args = [
  "-y",
  "@modelcontextprotocol/server-postgres",
  "postgresql://mcp_user:password@/production_db"
]

4. MySQL MCP Server (mysql-mcp-server)

[mcp_servers.mysql]
command = "npx"
args = [
  "-y",
  "mysql-mcp-server@0.1.4",
  "mysql://user:password@/mydb"
]

There is no @modelcontextprotocol/server-mysql package. mysql-mcp-server provides read-only access and is maintained at github.com/dpflucas/mysql-mcp-server.

5. Local Filesystem MCP Server (@modelcontextprotocol/server-filesystem)

Gives Codex scoped read/write access to project directories without unbounded file access. Pass the absolute path to the directory you want to expose — narrow it to the specific project rather than your home directory:

[mcp_servers.filesystem]
command = "npx"
args = [
  "-y",
  "@modelcontextprotocol/server-filesystem@2026.8.31",
  "/absolute/path/to/your-project"
]

6. Community Codex Server (@nothing1024/codex-mcp-server)

For community extensions and custom agent tools:

[mcp_servers.codex-bridge]
command = "npx"
args = ["-y", "@nothing1024/codex-mcp-server"]

Troubleshooting "Codex CLI Giving MCP Errors"

1. spawn npx ENOENT (Executable Not Found)

• ▸Symptom: codex mcp list shows Failed with Error: spawn npx ENOENT.
• ▸Cause: Codex CLI is running in a shell environment where npx or node is not in the system PATH.
• ▸Fix: On Windows, specify the full absolute path to npx.cmd:
  tomlCopy

  command = "C:\\Program Files\\nodejs\\npx.cmd"

  On macOS/Linux:
  tomlCopy

  command = "/usr/local/bin/npx"

2. Server Crashes or Exits Immediately

• ▸Symptom: Server starts but immediately transitions to Failed.
• ▸Diagnosis: Run codex mcp logs <server_name> to view stderr output.
• ▸Common Fix: Missing required environment variables. Verify token names match the server spec exactly (e.g. GITHUB_PERSONAL_ACCESS_TOKEN, not GITHUB_TOKEN).

3. Restarting an MCP Server

When updating config.toml or rotating API credentials, reload the server without restarting Codex:

codex mcp restart <server_name>

To reload all servers at once:

codex mcp reload

Interactive Workbench & Config Generator

Generate tailored multi-client configurations for Claude, Cursor, Windsurf, and OpenAI Codex CLI in one click using our interactive tools:

• ▸Open Visual Config Generator
• ▸Validate Config in Linter
• ▸Browse Full MCP Server Directory
• ▸Review MCP Error Codes & Solutions