MCP Servers

The Model Context Protocol (MCP) extends Codex's capabilities by connecting it to external tools, databases, and services. MCP is an open standard — originally created by Anthropic and now widely adopted — that provides a standardized way for AI applications to interact with external systems.

Supported Transports#

Codex supports two types of MCP servers:

| Transport | Description | Example | |-----------|-------------|---------| | STDIO | Local process started by a command | npx-based servers, local tools | | Streamable HTTP | Remote server accessed at a URL | Figma, cloud APIs, SaaS tools |

Adding MCP Servers#

Option 1: Using the CLI#

# Add an STDIO server
codex mcp add context7 -- npx -y @upstash/context7-mcp

# Add with environment variables
codex mcp add my-server --env API_KEY=sk-... -- npx my-mcp-server

Option 2: Editing config.toml#

Add server entries directly to ~/.codex/config.toml:

# STDIO server (local process)
[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]

# Streamable HTTP server (remote)
[mcp_servers.figma]
url = "https://mcp.figma.com/mcp"
bearer_token_env_var = "FIGMA_OAUTH_TOKEN"

Viewing Active Servers#

• CLI TUI: Type /mcp to see active servers
• IDE Extension: Select MCP settings from the gear menu

Popular MCP Servers#

Figma (Design to Code)#

[mcp_servers.figma]
url = "https://mcp.figma.com/mcp"
bearer_token_env_var = "FIGMA_OAUTH_TOKEN"

Enables bidirectional design workflows — pull Figma designs into code, or push code-generated UI back to Figma.

OpenAI Docs#

[mcp_servers.openai_docs]
url = "https://developers.openai.com/mcp"

Access OpenAI's developer documentation directly from Codex. This is a documentation-only server — it does not call the API on your behalf.

Context7 (Developer Documentation)#

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

Provides contextual developer documentation for popular frameworks and libraries.

Database Servers#

[mcp_servers.postgres]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-postgres"]
env = { DATABASE_URL = "postgresql://..." }

Configuration Options#

Each MCP server entry supports:

| Key | Required | Description | |-----|----------|-------------| | command | Yes (STDIO) | Command to start the server | | args | No | Arguments for the command | | url | Yes (HTTP) | Server URL for streamable HTTP | | env | No | Environment variables for the server | | bearer_token_env_var | No | Env var name for Authorization header | | http_headers | No | Static headers to send | | env_http_headers | No | Headers with values from env vars | | startup_timeout_sec | No | Server start timeout (default: 10) | | tool_timeout_sec | No | Tool execution timeout | | required | No | Fail if server cannot initialize |

Project-Scoped Servers#

Add MCP servers to .codex/config.toml in your project root for project-specific tools. These are only loaded for trusted projects.

# .codex/config.toml (project root)
[mcp_servers.project_docs]
command = "npx"
args = ["-y", "my-project-mcp-server"]

OAuth Configuration#

For MCP servers that use OAuth:

# Fixed callback port (if your OAuth provider requires it)
mcp_oauth_callback_port = 3456

# Custom callback URL (for remote devboxes)
mcp_oauth_callback_url = "https://devbox.example.com/oauth/callback"

Running Codex as an MCP Server#

You can expose Codex itself as an MCP server for use by other tools:

codex mcp serve

This lets you orchestrate Codex from the OpenAI Agents SDK or any other MCP client, enabling complex multi-agent pipelines.

## Troubleshooting

• Server fails to start: Check that the command exists and dependencies are installed
• Timeout errors: Increase startup_timeout_sec for slow-starting servers
• Missing tools: Verify the server exposes the tools you expect with /mcp in the TUI
• Auth issues: Ensure environment variables are set and accessible

Next Steps#

• AGENTS.md Guide — Project configuration
• Safety Modes — Sandbox and approval settings
• Multi-Agent — Use MCP with multi-agent workflows