How to Set Up MCP Servers with OpenAI Codex CLI

The Model Context Protocol (MCP) extends OpenAI Codex CLI's capabilities by connecting it to external tools, databases, and services. This guide covers everything you need to configure MCP servers and unlock powerful integrations for your development workflow.

What is MCP?

MCP (Model Context Protocol) is an open standard that provides a standardized way for AI applications to interact with external systems. Originally created by Anthropic, MCP has been adopted across the AI ecosystem including OpenAI Codex CLI.

With MCP servers configured, you can ask Codex CLI to:

• Access GitHub repositories, issues, and pull requests directly
• View Figma designs and translate them to code
• Automate browsers with Playwright for testing and scraping
• Monitor errors in Sentry and suggest fixes
• Query databases like Supabase and analyze results
• Connect to any API with custom MCP server implementations

Prerequisites

Before configuring MCP servers, ensure you have:

• Codex CLI installed (see our installation guide)
• Node.js 18+ for npm-based STDIO servers (run node --version to check)
• Network access for remote HTTP servers
• Credentials for any services you want to connect (API keys, OAuth tokens)

Understanding MCP Server Types

Codex CLI supports two types of MCP servers:

Choose STDIO for local tools and development utilities. Choose HTTP for cloud services and third-party integrations.

Managing MCP Servers via CLI

Codex CLI provides a complete set of commands for managing MCP servers.

Available Commands

# Add a new MCP server
codex mcp add <name>

# List all configured servers
codex mcp list

# Get details for a specific server
codex mcp get <name>

# Remove a server
codex mcp remove <name>

# Login to an MCP server (for OAuth-based servers)
codex mcp login <name>

# Logout from an MCP server
codex mcp logout <name>

Adding an STDIO Server

STDIO servers run as a local process. The codex mcp add command walks you through the configuration interactively, or you can edit the config file directly.

# Add a server interactively
codex mcp add github

# Then follow the prompts to configure command, args, and environment

Adding an HTTP Server

HTTP servers connect to remote URLs. After adding, you may need to authenticate.

# Add an HTTP server
codex mcp add sentry

# Complete authentication if required
codex mcp login sentry

Configuration File Format

MCP server configurations are stored in ~/.codex/config.toml. You can edit this file directly for advanced configurations.

STDIO Server Configuration

[mcp_servers.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/Users/yourname/projects"]
env = {}
cwd = ""
startup_timeout_sec = 30
tool_timeout_sec = 60
enabled = true

HTTP Server Configuration

[mcp_servers.sentry]
url = "https://mcp.sentry.dev/sse"
bearer_token_env_var = "SENTRY_AUTH_TOKEN"
http_headers = {}
startup_timeout_sec = 30
tool_timeout_sec = 60
enabled = true

Configuration Parameters

Popular Compatible MCP Servers

Here are configurations for commonly used MCP servers that work with Codex CLI:

Context7 (Documentation Search)

Context7 provides access to up-to-date library documentation:

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]

Usage: Ask Codex to "use context7 to find the latest React hooks documentation."

GitHub Server

Access GitHub repositories, issues, and pull requests:

[mcp_servers.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
env = { GITHUB_PERSONAL_ACCESS_TOKEN = "ghp_your_token_here" }

Create a Personal Access Token with appropriate repository permissions.

Figma Server

Translate Figma designs directly to code:

[mcp_servers.figma]
command = "npx"
args = ["-y", "@anthropic/figma-mcp-server"]
env = { FIGMA_ACCESS_TOKEN = "your_figma_token" }

Get your token from Figma Account Settings under Personal Access Tokens.

Playwright Server (Browser Automation)

Control browsers for testing and web scraping:

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

Requires Playwright browsers to be installed: npx playwright install

Sentry Server (Error Monitoring)

Monitor and analyze application errors:

[mcp_servers.sentry]
url = "https://mcp.sentry.dev/sse"
bearer_token_env_var = "SENTRY_AUTH_TOKEN"

Set the SENTRY_AUTH_TOKEN environment variable with your Sentry Auth Token.

Supabase Server

Query and manage Supabase databases:

[mcp_servers.supabase]
command = "npx"
args = ["-y", "@supabase/mcp-server"]
env = { SUPABASE_URL = "https://yourproject.supabase.co", SUPABASE_ANON_KEY = "your_anon_key" }

Authentication Methods

Bearer Token Authentication

For HTTP servers requiring API keys:

1. Set the token in an environment variable:

export SENTRY_AUTH_TOKEN="your-token-here"

2. Reference it in the configuration:

[mcp_servers.sentry]
url = "https://mcp.sentry.dev/sse"
bearer_token_env_var = "SENTRY_AUTH_TOKEN"

OAuth Authentication

Some MCP servers support OAuth flows:

# Initiate OAuth login
codex mcp login sentry

# This opens a browser for authentication
# After completing OAuth, the token is stored automatically

# To logout and revoke access
codex mcp logout sentry

Environment Variable Tokens

For STDIO servers, pass tokens via the env parameter:

[mcp_servers.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
env = { GITHUB_PERSONAL_ACCESS_TOKEN = "${GITHUB_TOKEN}" }

The ${GITHUB_TOKEN} syntax references an environment variable from your shell.

Controlling Tool Access

You can limit which tools from an MCP server are available to Codex:

Whitelist Specific Tools

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

Blacklist Specific Tools

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

This is useful for restricting potentially dangerous operations while still enabling read access.

Running Codex as an MCP Server

Codex CLI can also run as an MCP server itself, allowing other applications to use Codex's capabilities:

codex mcp-server

This starts Codex in server mode, listening for MCP protocol requests. Other MCP-compatible applications can then connect to Codex.

Known Limitations

Be aware of these current limitations when using MCP with Codex CLI:

STDIO Only for Local Servers

Local MCP servers must use the STDIO transport. Server-Sent Events (SSE) transport is not currently supported for local servers.

Global Configuration Only

MCP server configurations are stored globally in ~/.codex/config.toml. There is no per-project configuration option, unlike Claude Code which supports project-scoped .mcp.json files.

VS Code Extension Compatibility

There are known issues with MCP server functionality when using Codex CLI through VS Code extensions (see GitHub issue #6465). For the most reliable MCP experience, use Codex directly from the terminal.

Known Issues

• Self-reference hanging: Configuring Codex as its own MCP server can cause infinite loops (#6664)
• Windows timeout issues: Some users experience connection timeouts on Windows (#2555)

Troubleshooting

"spawn npx ENOENT" Error

Codex cannot find the npx executable. Solutions:

1. Use absolute paths to Node.js binaries:

[mcp_servers.myserver]
command = "/usr/local/bin/npx"
args = ["-y", "@some/mcp-server"]

2. Find your npx path:

which npx

Server Startup Timeout

If servers fail to start within the default timeout:

[mcp_servers.slow_server]
command = "npx"
args = ["-y", "@some/slow-server"]
startup_timeout_sec = 60  # Increase from default 30

Tool Execution Timeout

For long-running operations:

[mcp_servers.database]
command = "npx"
args = ["-y", "@some/database-server"]
tool_timeout_sec = 120  # Increase from default 60

Authentication Failures

If OAuth or token authentication fails:

1. Clear existing credentials:

codex mcp logout <server-name>

2. Verify environment variables are set:

echo $GITHUB_TOKEN

3. Re-authenticate:

codex mcp login <server-name>

Check Server Status

View all configured servers and their status:

codex mcp list

Get detailed information about a specific server:

codex mcp get github

Security Best Practices

1. Use environment variables for tokens instead of hardcoding in config.toml
2. Limit tool access using enabled_tools or disabled_tools when possible
3. Use read-only credentials for database servers when write access is not needed
4. Rotate API tokens regularly for connected services
5. Review server permissions before adding new MCP servers
6. Avoid sensitive data in server arguments that might be logged

Discovering More MCP Servers

The MCP ecosystem is growing rapidly. Find additional servers at:

• Official MCP Servers Repository - Reference implementations
• Awesome MCP Servers - Community curated list
• MCP.so - MCP server directory
• Smithery.ai - MCP marketplace

Next Steps

• Read about image input with Codex CLI for design-to-code workflows
• Learn how to resume sessions to maintain context across conversations
• Explore code review features for pull request analysis
• Compare with Claude Code MCP setup if you use multiple AI tools