Skip to content

MCP Servers for Codex

This guide describes what MCP servers are and how to add them to Codex.

MCP Servers

MCP stands for Model Context Protocol. An MCP server exposes external tools, data sources, or services to Codex through a standard interface.

MCP servers are useful because they let Codex interact with systems outside the repository without hardcoding those integrations into Codex itself.

Common MCP server uses include:

  • Reading documentation
  • Querying issue trackers
  • Searching internal systems
  • Inspecting browser state
  • Accessing databases or APIs with approved tools

Use MCP servers carefully. They can expand what Codex can access, so configure only the tools needed for the workflow and avoid exposing secrets unnecessarily.

Adding MCP Servers to Codex

Codex reads MCP server configuration from config.toml. The VS Code extension and CLI share this configuration.

For a global MCP server, edit:

$HOME\.codex\config.toml

For a trusted project-specific MCP server, use a project config file:

<repo_root>\.codex\config.toml

Add MCP servers under [mcp_servers.<server_name>].

Example STDIO server configuration:

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
enabled = true
startup_timeout_sec = 20
tool_timeout_sec = 45

Example HTTP server configuration:

[mcp_servers.chrome_devtools]
url = "http://localhost:3000/mcp"
enabled = true
startup_timeout_sec = 20
tool_timeout_sec = 45

After updating MCP configuration:

  1. Save config.toml.
  2. Restart VS Code or reload the Codex extension.
  3. Open the Codex pane.
  4. Verify the MCP server appears in the available tools or server list.
  5. Start a new Codex session if the current one does not pick up the change.

Adding MCP Servers Directly to VS Code

VS Code also supports MCP server configuration directly. This is useful when you want MCP servers available to VS Code features outside Codex, or when your team wants to share MCP configuration through the repository.

VS Code MCP configuration can be stored in two places:

  • Workspace: <repo_root>\.vscode\mcp.json
  • User profile: opened through the Command Palette with MCP: Open User Configuration

Use workspace configuration for MCP servers that should be shared with the repository. Use user configuration for personal tools, personal credentials, or servers that should be available across workspaces.

Example .vscode\mcp.json file:

{
  "servers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"]
    },
    "chrome_devtools": {
      "type": "http",
      "url": "http://localhost:3000/mcp"
    }
  }
}

You can also add servers through the VS Code Command Palette:

  1. Open the Command Palette.
  2. Run MCP: Add Server.
  3. Choose whether to add the server to the workspace or user configuration.
  4. Enter the server command, arguments, or URL.
  5. Run MCP: List Servers to verify the server is available.

VS Code also supports adding an MCP server from the command line:

code --add-mcp "{\"name\":\"fetch\",\"command\":\"uvx\",\"args\":[\"mcp-server-fetch\"]}"

Codex MCP configuration still lives in config.toml. VS Code native MCP configuration lives in mcp.json. Keep both files aligned if you need the same server available to Codex and other VS Code features.