mcp_servers.<id>.command

Values

A string naming the program to run. Codex spawns it directly, not through a shell, so the value is just the executable. Everything else goes in the sibling keys:

Key	Type	What it does
command	string	Program that starts the server (required for stdio)
args	array of strings	Arguments passed to that program
cwd	string	Working directory for the server process
env	table	Env vars set for the server
env_vars	array	Existing env vars allowed through to the server

enabled and required sit at the same level: enabled = false parks a server without deleting it, and required = true fails Codex startup if the server won’t initialize.

The official example, exactly as documented:

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

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

You can skip hand-editing entirely: codex mcp add context7 -- npx -y @upstash/context7-mcp writes the same block for you.

When to change it

1. Porting a JSON MCP config from Claude Desktop or Cursor. "command" and "args" map one-to-one; you’re just rewriting JSON as TOML. The number one mistake is stuffing the whole command line into command (it wants the bare program name, args go in args).
2. Pointing at a local build instead of a published package: command = "node" plus the script path in args.
3. HTTP servers don’t use command at all. Those get url instead, per the config reference.

Gotchas

No shell means no pipes, no &&, no variable expansion in the value.

Windows was rough for a while: npx is a .cmd script there, and Codex couldn’t resolve it through PATH, which is what #3510 and its full-path workarounds were about. PR #3828, merged November 2025, fixed .cmd/.bat resolution, so plain command = "npx" works on current builds.

A cold npx still has to download the package, and that can blow the default 10s startup timeout and throw a handshake error. See the handshake fix page and raise startup_timeout_sec if you hit it.

And a correct command still may not show up in the VS Code extension. #6465 is open with no maintainer response; servers work in the CLI but the extension doesn’t pick them up.

Related settings

• mcp_servers.<id>.env for secrets the server needs
• mcp_servers.<id>.enabled to park a flaky server
• “handshaking with MCP server failed” when the launch itself dies