Codex MCP: add, configure and debug MCP servers

What MCP adds to Codex

The Model Context Protocol (MCP) is a standard way for an agent to call tools that live outside it. An MCP server describes its tools (and optionally resources and prompts) and handles the requests. With a server configured, Codex can look up a ticket, read a Figma frame, drive a browser or query documentation, all from inside a session.

Codex supports two kinds of server:

Transport	How it runs	Auth options
STDIO	A local process Codex starts with a command	Environment variables
Streamable HTTP	A server at a URL	Bearer token, OAuth (with Client ID Metadata Documents or Dynamic Client Registration), ChatGPT session for trusted first-party servers

Codex also reads the instructions field a server returns during initialization and treats it as server-wide guidance alongside the tool list.

Add a server from the CLI

The quickest route is codex mcp add. For a local stdio server, put the launch command after --:

codex mcp add context7 -- npx -y @upstash/context7-mcp

Pass environment variables with repeated --env flags:

codex mcp add mytools --env API_BASE=https://api.example.com --env LOG_LEVEL=warn -- node ./mcp/server.js

For a remote server, use --url, and point --bearer-token-env-var at the variable holding a token if the server needs one:

codex mcp add docs --url https://developers.openai.com/mcp
codex mcp add internal --url https://mcp.internal.example.com/mcp --bearer-token-env-var INTERNAL_MCP_TOKEN

For servers that support OAuth, sign in after adding:

codex mcp login internal
codex mcp login internal --scopes read,write

Other subcommands:

codex mcp list            # all configured servers (add --json for scripts)
codex mcp get context7    # one server's config
codex mcp remove context7
codex mcp logout internal # drop stored OAuth credentials

Inside a session, /mcp lists the active servers and tools.

Configure in config.toml

Every codex mcp add writes a [mcp_servers.<name>] table to ~/.codex/config.toml. Editing that file directly gives you every option.

A stdio server:

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
env_vars = ["CONTEXT7_API_KEY"]          # forward these from your environment
startup_timeout_sec = 20

[mcp_servers.context7.env]
LOG_LEVEL = "warn"                      # set these literally

A streamable HTTP server:

[mcp_servers.figma]
url = "https://mcp.figma.com/mcp"
bearer_token_env_var = "FIGMA_OAUTH_TOKEN"
http_headers = { "X-Figma-Region" = "us-east-1" }

Option	Applies to	Meaning
command, args	stdio	How to start the server
env	stdio	Variables set for the server process
env_vars	stdio	Variables forwarded from your environment
cwd	stdio	Working directory for the server
url	HTTP	Server address
bearer_token_env_var	HTTP	Variable whose value is sent as a bearer token
http_headers, env_http_headers	HTTP	Static headers, or headers read from variables
startup_timeout_sec	both	Default 10
tool_timeout_sec	both	Default 60
enabled	both	false keeps the entry but turns the server off
required	both	true makes startup fail if the server cannot initialize
enabled_tools, disabled_tools	both	Allow list, then deny list
default_tools_approval_mode	both	auto, prompt, writes or approve

The configuration is shared: the CLI, the IDE extension and Codex in the ChatGPT desktop app read the same file, so a server you add once works in all three. In the IDE extension and desktop app you can also add servers from the settings screen (MCP servers, then Add server) and restart.

Project-scoped servers

A server that only one repository needs can go in that repository’s .codex/config.toml. Codex loads project config only when you have marked the project as trusted, which stops a cloned repository from starting arbitrary processes on your machine. Do not put tokens in a committed file; reference environment variables instead.

Control tools and approvals

Trimming tools keeps the tool list short and reduces the chance of an unwanted call:

[mcp_servers.github]
url = "https://example.com/github-mcp"
enabled_tools = ["get_issue", "list_pull_requests", "create_pull_request"]
default_tools_approval_mode = "writes"   # prompt for tools not marked read-only

[mcp_servers.github.tools.create_pull_request]
approval_mode = "prompt"

Independently of these settings, Codex asks for approval before a tool call that the server marks as destructive (unless the tool is also marked read-only). Treat approve mode as a deliberate choice for tools you trust completely.

Servers worth knowing

The servers below appear in Codex’s own documentation as common choices. Check each project’s README for its current install command.

• OpenAI Docs MCP: search and read OpenAI developer documentation. Remote server at https://developers.openai.com/mcp.
• Context7: current documentation for many libraries. npx -y @upstash/context7-mcp.
• Figma (local and remote): read designs and variables.
• Playwright: control and inspect a browser.
• Chrome DevTools: inspect and drive Chrome.
• Sentry: query errors and logs.
• GitHub: issues and pull requests beyond what git covers.

Debug a server that will not work

Work through these in order:

1. Is it configured? codex mcp list and codex mcp get <name> --json. A typo in the table name or a server left at enabled = false is common.
2. Does the command run outside Codex? Paste the command and args into a terminal. If npx or uvx is not on the PATH Codex sees, use an absolute path.
3. Are the variables there? Codex does not pass your whole shell environment to stdio servers, only a small default set such as HOME, PATH, SHELL and USER. An API key exported in your shell is invisible to the server until you list it in env_vars or set it in env.
4. Is it timing out? A first npx run can take longer than the default 10-second startup_timeout_sec while it downloads. Raise it, or install the package globally.
5. Does it need sign-in? For OAuth servers run codex mcp login <name>. The callback goes to a local loopback address, so run it on the machine where Codex runs.
6. Are tools slow? Raise tool_timeout_sec for that server.
7. Is output huge? Large tool results eat context. tools.<tool>.output_token_limit caps one tool’s output.

Inside a session, /mcp verbose shows server details. For a wider check, codex doctor produces a diagnostic report, and codex -c log_dir=./.codex-log writes a plaintext log you can search. In automation, set required = true on servers a job depends on: codex exec then exits with an error instead of carrying on without the server.

The codex-mcp-servers skill walks Codex through this checklist on your own config.

MCP servers from plugins

Plugins can bundle MCP servers. Those start from the plugin, so you do not set their command, but you can still control them under the plugin’s key:

[plugins."sample@test".mcp_servers.sample]
enabled = true
default_tools_approval_mode = "prompt"
enabled_tools = ["read", "search"]

MCP or a skill?

Question	MCP server	Skill
What it provides	Callable tools, live data	Instructions, references, scripts
Needs a running process or remote service	Yes	No
Context cost	Tool definitions while connected	Name and description; body on demand
Good for	Tickets, designs, browsers, internal APIs	Procedures, conventions, checklists

They combine well. A skill can describe a workflow (“triage a Sentry issue: fetch the event, find the release, reproduce locally”) and name the MCP tools to use. A skill can even declare the server it needs in agents/openai.yaml under dependencies.tools, and Codex can offer to install it. The comparison guide covers AGENTS.md and plugins too.

Building your own server

If no server exists for an internal system, write one with the official TypeScript or Python SDK, then add it with codex mcp add. The mcp-server-builder skill covers tool design, resources and testing. Note that the old codex mcp-server command, which ran Codex itself as an MCP server, has been removed; OpenAI points to the Codex app server for that use.