## Summary Add a `--scoped` / `-s` flag to `codex mcp add` so that MCP servers can be written directly to the project-local `.codex/config.toml` (at the nearest git root, or CWD fallback) instead of the global `~/.codex/config.toml`. ```sh # Global (current behaviour, unchanged) codex mcp add my-tool -- my-command # Project-scoped (new) codex mcp add --scoped my-tool -- my-command codex mcp add -s my-tool --url https://my-tool.example.com ``` ## Motivation Other agent CLIs already ship a fi

feat(mcp): add --scoped/-s flag to codex mcp add for project-local config

Open 💬 2 comments Opened May 19, 2026 by Rodriguespn

Summary

Add a --scoped / -s flag to codex mcp add so that MCP servers can be written directly to the project-local .codex/config.toml (at the nearest git root, or CWD fallback) instead of the global ~/.codex/config.toml.

# Global (current behaviour, unchanged)
codex mcp add my-tool -- my-command

# Project-scoped (new)
codex mcp add --scoped my-tool -- my-command
codex mcp add -s my-tool --url https://my-tool.example.com

Motivation

Other agent CLIs already ship a first-class flag for this:

Claude Code (--scope project) — docs: writes to .mcp.json at the project root, committed alongside the code and shared with teammates.
Gemini CLI (-s local / --scope local) — docs: similarly targets the repository root config.

Codex already reads project-scoped MCP servers from .codex/config.toml (issue #13056 tracks related UX pain), but codex mcp add only writes to ~/.codex/config.toml. Without this flag users must locate and hand-edit .codex/config.toml, which is error-prone.

Proposed behaviour

codex mcp add --scoped <NAME> ... — walks up from CWD looking for a .git directory; if found, uses <git-root>/.codex/config.toml; otherwise uses <cwd>/.codex/config.toml.
Creates .codex/ directory if it does not yet exist.
All other mcp add options (--env, --url, --bearer-token-env-var, etc.) remain valid.
Success message distinguishes global vs. project-scoped: Added project-scoped MCP server '<name>' to <path>.

Draft PR

https://github.com/Rodriguespn/codex/pull/1 (from fork Rodriguespn/codex, branch feat/mcp-add-scoped)

View original on GitHub ↗

2 Comments

saidelike · 3 months ago

The workaround for now is to create a project_dir/.codex/config.toml with what you need to override in there.

e.g.

Add the MCP server globally:

% codex mcp add chrome-devtools -- npx chrome-devtools-mcp@latest

Initially the MCP server is enabled globally, so let's disable it by adding enabled = false:

~/.codex/config.toml:

[mcp_servers.chrome-devtools]
command = "npx"
args = ["chrome-devtools-mcp@latest"]
enabled = false

project_dir% codex mcp list          
Name             Command  Args                        Env  Cwd  Status    Auth       
chrome-devtools  npx      chrome-devtools-mcp@latest  -    -    disabled  Unsupported

Enable the MCP server in your project:

project_dir/.codex/config.toml:

[mcp_servers.chrome-devtools]
command = "npx"
args = ["chrome-devtools-mcp@latest"]
enabled = true

project_dir% codex mcp list        
Name             Command  Args                        Env  Cwd  Status   Auth       
chrome-devtools  npx      chrome-devtools-mcp@latest  -    -    enabled  Unsupported

Rodriguespn · 3 months ago

Thank you for the explanation @saidelike. The workaround works, but I would like to have an easier way to scope MCP servers to my project without having to manually create or modify the config.toml file.

Other AI agents like Claude Code or Gemini CLI already allow this by passing the --scope flag to their mcp add command.
I've put together this PR to show what this flag's behavior would look like in codex.