Codex MCP Servers#

What it is#

Codex CLI supports the Model Context Protocol (MCP) to extend the agent with external tools — filesystem access, databases, APIs, browser automation, and more. MCP servers are configured in ~/.codex/config.toml under [mcp_servers.<id>] tables. Unlike Claude Code (where MCP is configured with codex mcp add), Codex uses pure TOML configuration.

How Codex finds servers#

Codex enumerates MCP servers by walking the merged config: it reads every [mcp_servers.<id>] table in the global ~/.codex/config.toml, then layers project-level <project>/.codex/config.toml on top (project keys win for the same <id>). Servers marked enabled = false are kept in the config but skipped at startup. There is no separate mcp.json file.

codex --print-config | rg "mcp_servers"

Output:

[mcp_servers.filesystem]
[mcp_servers.github]
[mcp_servers.postgres]

config.toml structure#

[mcp_servers.<server-id>]
command     = "npx"
args        = ["-y", "@modelcontextprotocol/server-filesystem", "/home/alice/work"]
env         = { MCP_TOKEN = "secret" }
enabled     = true
enabled_tools = []                # empty = all tools enabled
startup_timeout_sec      = 30
tool_timeout_sec         = 60
default_tools_approval_mode = "auto"  # "auto" | "manual"
supports_parallel_tool_calls = true

Output: (none — TOML config)

All [mcp_servers.*] keys#

Adding MCP servers#

The fastest way to add a server is to drop a [mcp_servers.<id>] block into ~/.codex/config.toml and restart Codex. The server process is launched lazily on the first session that needs it, and lives for the duration of that session. For HTTP/SSE servers the launch is the same — Codex still spawns the process; it just speaks HTTP over the spawned process’s stdin/stdout-bridged loopback port. There is no daemon mode.

stdio server (most common)#

[mcp_servers.filesystem]
command = "npx"
args    = ["-y", "@modelcontextprotocol/server-filesystem", "/home/alice/projects"]
enabled = true

Output: (none — TOML config)

HTTP/SSE server#

[mcp_servers.my-api]
command = "python3"
args    = ["-m", "my_mcp_server", "--port", "8080"]
env     = { MY_API_KEY = "abc123" }
startup_timeout_sec = 60

Output: (none — TOML config)

Disable a server temporarily#

[mcp_servers.filesystem]
command = "npx"
args    = ["-y", "@modelcontextprotocol/server-filesystem", "/home/alice/projects"]
enabled = false

Output: (none — TOML config)

Remote (SSE / streamable HTTP) server#

For a remote MCP server (one exposed by a SaaS API), point Codex at a small shim that proxies stdio to HTTP. The community mcp-remote package wraps any URL into the stdio transport Codex expects.

[mcp_servers.linear]
command = "npx"
args    = ["-y", "mcp-remote", "https://mcp.linear.app/sse"]
env     = { LINEAR_API_KEY = "lin_oauth_..." }
startup_timeout_sec = 60

Output: (none — TOML config)

Disabling a server temporarily#

Set enabled = false to keep the config block around but skip the launch. Faster than commenting the whole table out, and round-trips through codex --print-config cleanly.

Managing servers with codex mcp#

The codex mcp subcommand is read-only — it lists, inspects, and tests, but does not edit config. To add or remove servers, edit config.toml directly (Codex’s design choice: no hidden state).

List configured MCP servers:

codex mcp list

Output:

filesystem   enabled   npx -y @modelcontextprotocol/server-filesystem /home/alice/projects
my-api       disabled  python3 -m my_mcp_server --port 8080

Test a server (start it, list its tools, then exit):

codex mcp test filesystem

Output:

Starting filesystem… ok
Tools:
  read_file(path: string) -> string
  write_file(path: string, content: string) -> void
  list_directory(path: string) -> string[]
  search_files(pattern: string, dir?: string) -> string[]
Server exited cleanly.

Tail an MCP server’s stderr for debugging:

codex mcp logs filesystem --follow

Output:

[mcp:filesystem] listening on stdio
[mcp:filesystem] tool call: read_file {"path": "/home/alice/notes.md"}
[mcp:filesystem] tool result: 1428 bytes

Show details for a specific server:

codex mcp show filesystem

Output:

Name:     filesystem
Command:  npx -y @modelcontextprotocol/server-filesystem /home/alice/projects
Status:   enabled
Tools:    read_file, write_file, list_directory, move_file, search_files

Runtime inspection with /mcp#

/mcp is a TUI-only slash command that prints the live state of MCP servers — which ones are running, which tools they expose, and recent tool-call counts. It is the fastest way to verify your config without leaving the session. Inside an active session, use /mcp to see which servers are connected and what tools they expose:

/mcp

Output (inline in TUI):

Connected MCP servers:
  filesystem   [connected]
    read_file(path: string) → string
    write_file(path: string, content: string) → void
    list_directory(path: string) → array
    search_files(pattern: string, dir?: string) → array

Restart a server without leaving the session (useful after editing its config):

/mcp restart filesystem

Output (inline in TUI):

Stopping filesystem… ok
Starting filesystem… ok
4 tools available

Disable a server for the rest of the session only:

/mcp disable github

Output (inline in TUI):

github disabled for this session.

Tool approval modes#

Per-server tool approval is controlled by default_tools_approval_mode. The setting governs whether a tool call from this server pauses for user confirmation before executing. The default is "auto" (run immediately, in keeping with the session’s overall approval_policy); "manual" forces a per-call prompt even when the session’s policy says never.

[mcp_servers.filesystem]
command = "npx"
args    = ["-y", "@modelcontextprotocol/server-filesystem", "/home/alice/projects"]
default_tools_approval_mode = "manual"  # Prompt before every tool call

The global approval_policy in config.toml and the per-server default_tools_approval_mode interact:

• If the session’s approval_policy is "never", server tools run without prompts regardless of default_tools_approval_mode.
• "manual" forces a prompt for each call even if the global policy is "on-request".

Per-tool approval override (more granular than the per-server mode):

[mcp_servers.filesystem]
command       = "npx"
args          = ["-y", "@modelcontextprotocol/server-filesystem", "/home/alice/projects"]
default_tools_approval_mode = "auto"

[mcp_servers.filesystem.tool_approvals]
write_file = "manual"   # write_file always prompts even though server default is auto
move_file  = "manual"

Whitelisting specific tools#

enabled_tools is a small but powerful safety knob: rather than disabling a server, you can run it with a curated subset of its tools exposed. Good for filesystem servers (read-only mode) and database servers (omit drop_table).

[mcp_servers.filesystem]
command       = "npx"
args          = ["-y", "@modelcontextprotocol/server-filesystem", "/home/alice/projects"]
enabled_tools = ["read_file", "list_directory"]  # write_file and others disabled

Output: (none — TOML config)

Inverse pattern — disabled_tools keeps the whitelist implicit but blocks specific dangerous tools:

[mcp_servers.postgres]
command        = "npx"
args           = ["-y", "@modelcontextprotocol/server-postgres", "postgresql://localhost/mydb"]
disabled_tools = ["execute_query", "alter_table"]

Output: (none — TOML config)

Project-level MCP config#

Project-level MCP is the canonical pattern for “this repo needs Postgres MCP pointed at its local dev DB.” The project’s .codex/config.toml is merged on top of the user-level config — including [mcp_servers.*] tables — so per-repo servers come online automatically when you launch Codex in that directory, and vanish when you leave. When a project directory is trusted, .codex/config.toml inside it overlays the user config. This lets you declare project-specific MCP servers without polluting your global config:

# /home/alice/myproject/.codex/config.toml
[mcp_servers.project-db]
command = "python3"
args    = ["-m", "mcp_postgres_server"]
env     = { DATABASE_URL = "postgresql://localhost/mydb" }

Output: (none — TOML config)

Trust the project first:

# ~/.codex/config.toml
[projects."/home/alice/myproject"]
trust_level = "trusted"

Output: (none — TOML config)

Popular MCP servers#

Install and run any of these:

npx -y @modelcontextprotocol/server-github

Output: (none — starts server process; Codex connects automatically)

Codex as an MCP server (other direction)#

Codex itself can act as an MCP server, exposing its own capabilities to another MCP client. This is the foundation of the “Codex inside Codex” sub-agent pattern (see subagents). Launch the server with:

codex mcp serve --port 8765

Output:

Codex MCP server listening on stdio (port 8765 bridged)
Exposed tools: codex_exec, codex_resume, codex_apply

A consumer can then add it as a regular MCP server:

[mcp_servers.inner-codex]
command = "codex"
args    = ["mcp", "serve"]

Output: (none — TOML config)

Secrets handling#

Embedding tokens directly in config.toml is convenient but lands secrets in plain text. Codex supports two safer patterns:

Reference an env var#

[mcp_servers.github]
command = "npx"
args    = ["-y", "@modelcontextprotocol/server-github"]
env     = { GITHUB_TOKEN = "${env:GITHUB_TOKEN}" }

Output: (none — TOML config; ${env:NAME} is resolved at server start)

Reference a file#

[mcp_servers.github]
command = "npx"
args    = ["-y", "@modelcontextprotocol/server-github"]
env     = { GITHUB_TOKEN = "${file:~/.config/secrets/github_token}" }

Output: (none — TOML config; file contents trimmed of trailing newlines)

Common pitfalls#

1. npx -y re-downloads on every cold start. First-time launches of an npx -y @modelcontextprotocol/server-* server can take 5–15 seconds. Bump startup_timeout_sec to 60 if you see “MCP server timed out” errors on slow networks. Once cached, subsequent runs start in under a second.

2. stdio MCP servers must NOT write to stdout for anything other than protocol messages. A stray print() or console.log() corrupts the JSON-RPC stream and disconnects the server. Always write debug output to stderr (which Codex captures into logs/).

3. enabled_tools = [] means “all tools enabled,” not “no tools enabled.” This is a frequent footgun. To disable all tools from a server, use enabled = false instead.

4. Project-level MCP config requires trust_level = "trusted". A new repo’s .codex/config.toml is silently ignored. Run codex projects list to confirm.

5. default_tools_approval_mode = "manual" is overridden by --ask-for-approval never. The CLI flag wins. Use per-tool tool_approvals if you need certain tools to always prompt regardless of the session policy.

6. MCP servers don’t share file handles with Codex. A filesystem MCP server with args = ["/home/alice/work"] can only access that subtree, even if the Codex sandbox is set to danger-full-access. Configure the server’s allowed paths explicitly.

7. env = { … } clobbers, doesn’t merge. Any variable not listed under env is inherited from the parent process. Listed variables are set to the configured value; there is no “remove” syntax.

8. HTTP-only MCP servers must be wrapped. Codex’s MCP transport is stdio. Use mcp-remote or write a small Python shim to bridge an SSE/streamable-HTTP server.

Real-world recipes#

Read-only Git inspection MCP#

A safe MCP setup for “summarise this repo” sessions — filesystem with reads only, plus a git MCP that exposes log/diff but not write operations.

[mcp_servers.fs-readonly]
command       = "npx"
args          = ["-y", "@modelcontextprotocol/server-filesystem", "/home/alice/myproject"]
enabled_tools = ["read_file", "list_directory", "search_files"]

[mcp_servers.git]
command        = "npx"
args           = ["-y", "@modelcontextprotocol/server-git", "/home/alice/myproject"]
disabled_tools = ["commit", "push", "reset"]

Output: (none — TOML config)

Then:

codex --sandbox read-only --ask-for-approval never "Summarise the architecture of this repo."

Output:

[agent uses fs-readonly + git MCP to summarise without writing anything]

Per-project Postgres MCP#

Drop a .codex/config.toml into a repo whose dev DB is local. Codex picks it up automatically once the project is trusted.

# myproject/.codex/config.toml
[mcp_servers.dev-db]
command = "npx"
args    = ["-y", "@modelcontextprotocol/server-postgres", "postgresql://localhost:5432/myproject_dev"]
default_tools_approval_mode = "manual"
disabled_tools = ["execute_query"]

Output: (none — project-scoped TOML)

Disable a noisy MCP server for one session#

If a server is generating too many tokens of background context, disable it for the current TUI session without editing config:

/mcp disable brave-search

Output (inline in TUI):

brave-search disabled for this session.

Validate a new server before adding it globally#

Before adding a server to config.toml, smoke-test it standalone:

codex mcp test --config /tmp/test-mcp.toml my-new-server

Output:

Starting my-new-server… ok
Tools:
  do_thing(arg: string) -> string
Server exited cleanly.

Mirror MCP config across machines#

Keep a single source of truth in dotfiles, symlinked into ~/.codex:

ln -sf ~/dotfiles/codex/config.toml ~/.codex/config.toml

Output: (none — creates symlink)