Configure MCP Servers in Codex

Connecting your OpenAI Codex CLI to external tools is done via the Model Context Protocol (MCP). This guide will walk you through setting up your config.toml file to integrate various MCP servers step-by-step.

Prerequisites

• ▸OpenAI Codex CLI installed (v2.0.0 or higher)
• ▸Node.js or Python (depending on the MCP servers you want to run)

Locating Your Configuration File

The Codex CLI reads its configuration from a config.toml file. Depending on your operating system, you can find or create this file in the following locations:

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

Adding Your First MCP Server

Open the config.toml file in your favorite text editor. MCP servers are defined under the [mcpServers] table. Each server needs a unique name, a command to execute, and optional arguments or environment variables.

Here is an example of adding the official Filesystem MCP server, which allows Codex to read and write files in a specific directory:

[mcpServers.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "C:/Users/richa/github"]

Breaking Down the Configuration

1. ▸[mcpServers.filesystem]: This declares a new server named filesystem.
2. ▸command: The executable to run. We use npx to fetch and run the server dynamically.
3. ▸args: The arguments passed to the command. Here, we pass -y to skip the installation prompt, the package name, and the directory we want to expose to Codex.

Adding Environment Variables

Some MCP servers, like the GitHub or Database servers, require authentication tokens or connection strings. You can pass these securely using the env table.

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

  [mcpServers.github.env]
  GITHUB_PERSONAL_ACCESS_TOKEN = "ghp_your_token_here"

Advanced Configuration: Python Servers

If you are using an MCP server written in Python (like the SQLite server), you can configure it using the uv tool or standard python commands:

[mcpServers.sqlite]
command = "uvx"
args = ["mcp-server-sqlite", "--db-path", "C:/Users/richa/github/my-database.db"]

Testing Your Configuration

Once you've saved your config.toml file, you can verify that the Codex CLI is able to connect to your configured servers by running:

codex mcp list

You should see a list of your configured servers along with their status (Connected or Failed). If a server fails to connect, double-check your paths and environment variables.

Next Steps

Now that you know how to configure servers, check out our guide on the Best MCP Servers for Codex to see what you can build!