Skip to content
AgentAtlas

Codex MCP servers: codex mcp add and [mcp_servers] in config.toml

How do I add an MCP server to Codex?

Run codex mcp add with a name and the server command, for example codex mcp add context7 -- npx -y @upstash/context7-mcp, or add a [mcp_servers.<name>] table to ~/.codex/config.toml. Use command and args for local stdio servers and url for remote streamable HTTP servers. Type /mcp in the Codex TUI to see which servers are active.

Compare: add an MCP server in every AI coding agent →

Add a server from the command line

General form for a stdio server

codex mcp add <server-name> --env VAR1=VALUE1 --env VAR2=VALUE2 -- <stdio server-command>

Example: Context7

codex mcp add context7 -- npx -y @upstash/context7-mcp
  • codex mcp list shows configured servers.
  • codex mcp --help shows all MCP commands.
  • codex mcp login <server-name> starts an OAuth sign-in for servers that support it.
  • /mcp in the Codex TUI shows your active servers.

Configure a local stdio server in config.toml

Servers live in [mcp_servers.<server-name>] tables in ~/.codex/config.toml, or in .codex/config.toml for trusted projects. Stdio servers need command. Optional keys are args, env, env_vars and cwd.

~/.codex/config.toml

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

[mcp_servers.context7.env]
MY_ENV_VAR = "MY_ENV_VALUE"

Configure a remote HTTP server

Streamable HTTP servers need url. You can pass a token from an environment variable with bearer_token_env_var and add headers with http_headers or env_http_headers.

~/.codex/config.toml

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

Server with a pre-registered OAuth client

codex mcp add example --url https://mcp.example.com --oauth-client-id my-client

For OAuth sign-in, run codex mcp login <server-name>. You can add --oauth-client-registration with auto (the default), cimd or dcr.

Limit tools, timeouts and approvals

  • startup_timeout_sec: defaults to 10.
  • tool_timeout_sec: defaults to 60.
  • enabled = false turns a server off without deleting it.
  • required = true makes startup fail if the server cannot start.
  • enabled_tools is an allow list. disabled_tools is a deny list applied after enabled_tools.
  • default_tools_approval_mode accepts auto, prompt, writes or approve. tools.<tool>.approval_mode overrides it for one tool.

~/.codex/config.toml

[mcp_servers.chrome_devtools]
url = "http://localhost:3000/mcp"
enabled_tools = ["open", "screenshot"]
disabled_tools = ["screenshot"]
default_tools_approval_mode = "prompt"
startup_timeout_sec = 20
tool_timeout_sec = 45
enabled = true

[mcp_servers.chrome_devtools.tools.open]
approval_mode = "approve"
output_token_limit = 30000

Sources

More Codex guides

Reviewed Oct 18, 2026. Settings change often; the linked vendor docs are the source of truth.

Built an MCP server? Get it listed everywhere →

Shipping an Android app? Google Play needs 12 testers for 14 days first. Get them with Tester Exchange →