Codex MCP configuration: shared config.toml setup for CLI and VSCode extension

When two tools share one config file, small mistakes break everything

Setting up MCP servers in the new Codex CLI and Codex VSCode extension presents a unique challenge that doesn't exist with other AI development tools. Unlike Claude Code's project-specific JSON configurations or other MCP clients with separate configuration systems, Codex CLI and the VSCode extension share a single ~/.codex/config.toml file. This architectural decision creates both convenience and complexity.

The convenience is obvious: configure an MCP server once, use it everywhere. The complexity emerges when you realize that a syntax error in your TOML configuration doesn't just break one tool—it breaks both simultaneously. When developers add a new MCP server and accidentally use malformed TOML syntax, both their terminal workflow and VSCode extension stop working until the configuration is fixed.

This shared configuration approach represents a fundamental departure from how other AI coding assistants handle MCP integration. Most tools treat CLI and editor integrations as separate systems with independent configurations. Codex's unified approach eliminates configuration duplication but requires understanding TOML syntax and the implications of shared state across development environments.

The learning curve is steeper than expected. Developers familiar with JSON-based MCP configurations in other tools need to adapt to TOML syntax. Those accustomed to separate CLI and editor configurations must understand how the shared configuration affects their existing workflows. The payoff comes in consistency—once configured correctly, MCP servers work identically across CLI and editor environments.

What makes this particularly challenging is Codex's current limitation to local server execution only. While Claude Code supports remote MCP servers over HTTP and SSE protocols, Codex requires all MCP servers to run locally as subprocesses using STDIO transport. This means you can use npx to dynamically install and run MCP servers locally, but you cannot connect to remote MCP services running on external servers. This constraint affects which MCP servers you can use and how you structure your development environment.

Understanding Codex's unique TOML configuration approach

Codex introduced MCP server support in September 2025 with a configuration model that differs significantly from other AI development tools. The decision to use TOML format in a shared configuration file reflects OpenAI's broader approach to unified tool experiences but creates specific implementation challenges.

The configuration file lives at ~/.codex/config.toml and must be created manually. Unlike many development tools that create default configuration files during installation, Codex expects developers to understand the configuration structure and create the file themselves. This approach assumes familiarity with TOML syntax and MCP server configuration patterns.

TOML (Tom's Obvious Minimal Language) provides a more readable alternative to JSON for configuration files, but it introduces syntax requirements that catch developers off guard. Unlike JSON's familiar bracket and quote patterns, TOML uses section headers, key-value pairs, and specific formatting rules that create different error patterns when mistakes occur.

# Basic structure - note the section header format
[mcp_servers.server-name]
command = "npx"
args = ["-y", "@package/server"]
env = { "API_KEY" = "value" }

The section name mcp_servers (with underscore, not hyphen) is critical. Using mcp-servers or mcpservers will cause Codex to ignore the configuration silently. This subtle naming requirement creates debugging challenges because the configuration appears correct but doesn't function.

The shared configuration model means that both Codex CLI and the VSCode extension read from the same file and expect identical syntax. When one tool works and another doesn't, the problem usually lies in how each tool interprets the configuration rather than syntax errors. However, when syntax errors exist, both tools fail simultaneously.

Environment variable handling in TOML requires specific syntax patterns. The env section uses inline table format with specific quoting and assignment patterns that differ from shell environment variables or JSON object notation. Understanding these patterns prevents authentication issues when configuring MCP servers that require API keys or tokens.

# Correct environment variable syntax
env = { "API_TOKEN" = "your-token", "DEBUG" = "true" }

# Incorrect - this breaks TOML parsing
env = { API_TOKEN: "your-token", DEBUG: true }

The array syntax for command arguments also follows TOML conventions rather than shell or JSON patterns. Arguments must be quoted strings in square brackets, with each argument as a separate string element. Shell patterns like "arg1 arg2" as a single string don't work correctly.

Codex's configuration approach prioritizes consistency over flexibility. While other MCP clients allow multiple configuration file locations and format options, Codex enforces a single file location and format. This constraint simplifies configuration discovery but requires understanding the specific patterns Codex expects.

The transport limitation to STDIO only affects which MCP servers can be configured. Remote servers accessible via HTTP or SSE protocols require local proxy solutions or can't be used at all. This limitation influences architecture decisions when choosing MCP servers for development workflows.

Complete MCP server configuration guide

Setting up MCP servers in Codex requires understanding the file structure, TOML syntax patterns, and the specific configuration options Codex supports. The process involves creating the configuration directory, writing properly formatted TOML, and restarting both CLI and extension to load changes.

Initial setup and directory creation

The configuration directory doesn't exist by default and must be created manually. This setup process establishes the foundation for all MCP server configurations:

# Create the Codex configuration directory
mkdir -p ~/.codex

# Create the configuration file
touch ~/.codex/config.toml

# Verify the file exists and has proper permissions
ls -la ~/.codex/config.toml

The directory permissions should allow read and write access for your user account. If permission issues occur, both Codex CLI and VSCode extension will fail to load MCP server configurations without clear error messages.

Basic TOML structure and syntax patterns

Understanding TOML syntax prevents configuration errors that break both tools simultaneously. The format requires specific section headers, key-value pairs, and array syntax that differs from JSON:

# Global Codex configuration (optional)
preferred_auth_method = "apikey"
model = "gpt-4"
model_provider = "openai"

# MCP servers section - note the underscore
[mcp_servers.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/directory"]

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
env = { "CONTEXT7_API_KEY" = "your-api-key" }

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

Each MCP server requires a unique identifier after the mcp_servers. prefix. This identifier becomes the server name that Codex uses internally, so choose descriptive names that reflect the server's purpose.

Command and argument configuration patterns

The command and args fields define how Codex launches the MCP server process. Understanding these patterns ensures reliable server startup:

# NPX-based server installation
[mcp_servers.snyk-security]
command = "npx"
args = ["-y", "snyk@latest", "mcp", "-t", "stdio"]

# Local development server
[mcp_servers.custom-server]
command = "node"
args = ["./build/server.js"]
cwd = "/path/to/project"

# Python-based server
[mcp_servers.python-server]
command = "python"
args = ["-m", "mcp_server.main"]
env = { "PYTHONPATH" = "/path/to/modules" }

The npx approach automatically downloads and runs the latest version of MCP servers, ensuring you have current implementations without manual installation management. For development workflows, this automatic updating can be beneficial or problematic depending on your stability requirements.

Local command paths require absolute paths or commands available in your system PATH. Using relative paths creates inconsistent behavior between CLI and VSCode extension execution contexts.

Environment variable and authentication setup

MCP servers often require authentication tokens, API keys, or configuration values passed through environment variables. Codex supports environment variable configuration through the env section:

[mcp_servers.brightdata-web]
command = "npx"
args = ["-y", "@brightdata/mcp"]
env = {
  "API_TOKEN" = "your-bright-data-api-key",
  "PRO_MODE" = "true",
  "TIMEOUT" = "30000"
}

[mcp_servers.supabase]
command = "npx"
args = ["-y", "@supabase/mcp-server-supabase@latest"]
env = {
  "SUPABASE_ACCESS_TOKEN" = "your-access-token",
  "SUPABASE_URL" = "https://your-project.supabase.co"
}

Environment variables in TOML use inline table syntax with specific formatting requirements. Each variable must be a quoted string, both key and value, with comma separation between multiple variables.

For security, consider using actual environment variables instead of hardcoded values in the configuration file:

# Set environment variables in your shell
export SUPABASE_ACCESS_TOKEN="your-token"
export BRIGHT_DATA_API_KEY="your-key"

# Reference them in TOML (this approach requires shell interpolation)
# Note: Direct environment variable references in TOML aren't supported by Codex
# You must use literal values in the config file

Working configuration examples

Here are complete, tested configurations for popular MCP servers that work with Codex's STDIO transport limitation:

# Web browsing and automation
[mcp_servers.playwright]
command = "npx"
args = ["-y", "@playwright/mcp@latest"]

# File system operations
[mcp_servers.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/Users/username/projects"]

# Security scanning
[mcp_servers.snyk]
command = "npx"
args = ["-y", "snyk@latest", "mcp", "-t", "stdio"]

# Web search and browsing
[mcp_servers.brightdata]
command = "npx"
args = ["-y", "@brightdata/mcp"]
env = { "API_TOKEN" = "your-api-token", "PRO_MODE" = "true" }

# Context management
[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
env = { "CONTEXT7_API_KEY" = "your-api-key" }

# Database operations
[mcp_servers.supabase]
command = "npx"
args = ["-y", "@supabase/mcp-server-supabase@latest", "--project-ref=your-project-ref"]
env = { "SUPABASE_ACCESS_TOKEN" = "your-supabase-access-token" }

After adding configurations, restart both Codex CLI and the Codex VSCode extension to load the new MCP servers. Changes to the configuration file don't take effect until both tools are restarted.

Validation and testing procedures

Verify MCP server configurations by testing functionality in both CLI and VSCode extension:

# Test Codex CLI with MCP servers
codex

# In the Codex CLI interface, try commands that would use MCP servers
# For example, with filesystem MCP: "list files in my project directory"
# With Playwright MCP: "open a browser and navigate to example.com"

In VSCode, open the Codex extension panel and test similar commands. If servers work in CLI but not VSCode, check that the Codex VSCode extension has been fully restarted and has reloaded the configuration.

Configuration errors often manifest as silent failures where commands that should use MCP servers fall back to standard Codex behavior without explanation. Understanding the expected behavior helps identify when MCP servers aren't loading correctly.

Troubleshooting shared configuration issues

The shared configuration model creates unique debugging challenges where errors affect multiple tools simultaneously. Understanding common failure patterns helps diagnose and resolve configuration issues efficiently.

TOML syntax validation and common errors

TOML syntax errors break both Codex CLI and VSCode extension simultaneously. The most common mistakes involve section headers, string quoting, and array formatting:

# Common syntax errors that break everything

# Wrong section name (underscore vs hyphen)
[mcp-servers.example]  # ❌ Wrong - should be mcp_servers
[mcp_servers.example]  # ✅ Correct

# Missing quotes in environment variables
env = { API_KEY = value }  # ❌ Wrong - value needs quotes
env = { "API_KEY" = "value" }  # ✅ Correct

# Incorrect array syntax
args = ["arg1" "arg2"]  # ❌ Wrong - missing comma
args = ["arg1", "arg2"]  # ✅ Correct

# Invalid characters in section names
[mcp_servers.my-server@latest]  # ❌ Wrong - special chars
[mcp_servers.my_server_latest]  # ✅ Correct

Use a TOML validator to check syntax before restarting Codex tools. Online TOML validators quickly identify parsing errors that might not be obvious when reading the configuration file.

MCP server connection and timeout issues

MCP servers that take too long to initialize cause timeout errors in the VSCode extension. GitHub issue #3289 documents this specific problem with Context7 and other servers:

# If servers timeout, try simpler configurations first
[mcp_servers.simple_test]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]

# Before complex servers with authentication
[mcp_servers.complex_server]
command = "npx"
args = ["-y", "@complex/mcp-server"]
env = { "API_KEY" = "key", "COMPLEX_CONFIG" = "value" }

Start with simple MCP servers like filesystem or basic tools to verify the configuration system works before adding servers that require network access or complex authentication.

Monitor Codex CLI output for MCP server connection messages. Successful connections typically show server loading messages during startup, while failures may show timeout errors or silent fallback to standard behavior.

VSCode extension-specific problems

The VSCode extension reads the same configuration file but may have different execution contexts that affect MCP server behavior:

1. Extension not recognizing configuration changes: Fully restart the Codex VSCode extension (not just reload window) after configuration changes
2. Permission issues: Ensure VSCode can read the ~/.codex/config.toml file and execute commands specified in the configuration
3. PATH differences: VSCode may have different PATH environment than your terminal, affecting command resolution

# Verify commands work in both contexts
which npx  # Check if npx is available
echo $PATH  # Compare PATH between terminal and VSCode terminal

# Test in VSCode integrated terminal
# Terminal > New Terminal, then try:
npx @playwright/mcp@latest --help

Command path and execution environment issues

MCP servers that work in terminal may fail in VSCode due to execution environment differences. Common issues include:

# Problematic - relative paths
[mcp_servers.local]
command = "./server"  # ❌ May not work in VSCode context

# Better - absolute paths or system commands
[mcp_servers.local]
command = "/full/path/to/server"  # ✅ Explicit path
cwd = "/project/directory"  # ✅ Set working directory

# Best - system PATH commands
[mcp_servers.npm_server]
command = "npx"  # ✅ Available in system PATH
args = ["-y", "@package/server"]

The cwd (current working directory) option helps when MCP servers expect to run from specific directories. This becomes important for development servers that load configuration files or dependencies from relative paths.

Authentication and API key problems

Environment variable configuration in TOML requires careful handling of special characters and proper quoting:

# Handle special characters in API keys
[mcp_servers.api_server]
env = {
  "API_KEY" = "key-with-dashes",  # ✅ Dashes OK in values
  "COMPLEX_KEY" = "key/with/slashes",  # ✅ Slashes OK in values
  "JSON_CONFIG" = "{\"key\": \"value\"}"  # ✅ Escaped quotes for JSON
}

Test authentication separately from Codex configuration. Many MCP servers include standalone testing modes that verify API keys and authentication before integration with Codex.

Configuration file permission and location issues

Incorrect file permissions or locations cause silent failures where neither CLI nor VSCode extension loads MCP servers:

# Verify configuration file permissions and location
ls -la ~/.codex/config.toml
# Should show read/write permissions for your user

# Check file contents are valid TOML
cat ~/.codex/config.toml

# Validate TOML syntax using Python (if available)
python -c "import tomllib; print('Valid TOML')" < ~/.codex/config.toml

The configuration file must be in the exact location ~/.codex/config.toml. Variations like .codex/config.toml (without tilde) or ~/.codex/codex.toml won't be recognized by either tool.

Debugging workflow for shared configuration problems

When both tools fail simultaneously, use this systematic debugging approach:

1. Isolate syntax issues: Validate TOML syntax first
2. Test minimal configuration: Start with one simple MCP server
3. Verify command availability: Test commands in both terminal and VSCode terminal
4. Check authentication separately: Validate API keys and tokens outside Codex
5. Monitor startup messages: Watch for connection success/failure messages
6. Test incrementally: Add one MCP server at a time to isolate problems

This systematic approach prevents the frustration of debugging multiple configuration issues simultaneously when the shared configuration model amplifies single errors across multiple tools.

Comparison with other MCP client configurations

Understanding how Codex's configuration approach differs from other MCP clients helps contextualize the design decisions and their implications for development workflows.

Codex vs Claude Code configuration models

Claude Code uses project-specific JSON configurations with multiple file location options, creating a fundamentally different approach from Codex's unified TOML model:

// Claude Code: ~/.claude.json
{
  "projects": {
    "/path/to/project": {
      "mcpServers": {
        "filesystem": {
          "command": "npx",
          "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path"]
        }
      }
    }
  }
}

# Codex: ~/.codex/config.toml
[mcp_servers.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/path"]

Claude Code's project-based isolation means different projects can have different MCP server configurations. This flexibility supports teams working on multiple projects with different tooling requirements. Codex's global configuration assumes consistent tooling needs across all projects.

The trade-offs become apparent in team environments. Claude Code's project-specific configs can be version-controlled and shared among team members, ensuring consistent MCP server setups. Codex's global configuration requires manual setup on each developer machine but provides consistency across all projects.

Configuration complexity and maintenance overhead

The complexity comparison reveals different approaches to configuration management:

Codex (Simple but Rigid):

• Single file location: ~/.codex/config.toml
• TOML syntax learning curve
• Global configuration affects all projects
• Manual setup required on each machine
• Shared CLI/editor configuration

Claude Code (Flexible but Complex):

• Multiple file location options
• Project-specific isolation
• CLI wizard for interactive setup
• JSON format familiar to most developers
• Separate authentication per project

Transport protocol support comparison

The key distinction is where the MCP server runs, not how it's installed:

Important: npx commands work perfectly with Codex because they download and run the server locally as a subprocess. The limitation is only for connecting to remote servers that are already running elsewhere.

Codex's STDIO-only limitation means remote MCP servers require local proxy solutions or can't be used at all. This constraint affects architecture decisions when building teams around MCP-powered development workflows.

For example, Linear's remote MCP server (mcp.linear.app) works directly with Claude Code but requires proxy solutions with Codex. This limitation influences tool selection based on required MCP server capabilities.

Team collaboration and configuration sharing

Different configuration approaches create different collaboration patterns:

Codex: Requires documentation and manual setup procedures for team members. Configuration can't be version-controlled easily since it's user-specific.

Claude Code: Project-specific configurations can be committed to repositories, ensuring team consistency. However, authentication still requires individual setup.

The collaboration implications become significant in team environments where consistent tooling matters for productivity and onboarding efficiency.

Performance and resource utilization

Configuration approaches affect system resource usage and startup performance:

Codex: Global configuration loads all MCP servers for every session, potentially consuming resources for unused servers. However, the unified model reduces configuration overhead.

Claude Code: Project-specific loading means only relevant MCP servers initialize, reducing resource usage but increasing configuration complexity.

Understanding these trade-offs helps teams choose appropriate MCP client strategies based on their development patterns, team size, and resource constraints. These considerations align with broader AI tool selection criteria that evaluate integration capabilities, workflow compatibility, and long-term maintenance requirements.

Best practices for shared configuration management

Managing Codex's shared configuration requires attention to detail since both CLI and extension depend on the same file. Here are the essential practices:

Configuration organization and backups

# Group servers by category with comments
# Development tools
[mcp_servers.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/Users/username/projects"]

# External services
[mcp_servers.brightdata]
command = "npx"
args = ["-y", "@brightdata/mcp"]
env = { "API_TOKEN" = "your-api-token" }

Always backup your configuration before changes:

cp ~/.codex/config.toml ~/.codex/config.toml.backup.$(date +%Y%m%d)

Environment variable security

Since Codex requires literal values in TOML, handle sensitive data carefully:

• Never commit API keys to version control
• Create sanitized template files for team sharing
• Document required environment variables without exposing actual values

Performance optimization

Comment out unused MCP servers rather than deleting them to preserve working configurations:

# High-frequency servers - keep enabled
[mcp_servers.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/path"]

# Project-specific - disable when not needed
# [mcp_servers.playwright]
# command = "npx"
# args = ["-y", "@playwright/mcp@latest"]

The shared configuration model works well when you treat the TOML file as critical infrastructure—test changes, maintain backups, and document configurations with the same care as other essential development tools.