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 ↗

This issue has 2 comments on GitHub. Read the full discussion on GitHub ↗