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.jsonat 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.gitdirectory; 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 addoptions (--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)
This issue has 2 comments on GitHub. Read the full discussion on GitHub ↗