Issue Station
Sign In
Tools hereToolbox

codex - ✅(Solved) Fix feat(mcp): add --scoped/-s flag to codex mcp add for project-local config [1 pull requests, 1 comments, 2 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
openai/codex#23487•Fetched 2026-05-20 03:49:01
View on GitHub
Comments
1
Participants
2
Timeline
6
Reactions
0
Author
RodriguespnRodriguespn
Participants
Keesan12Keesan12RodriguespnRodriguespn
Timeline (top)
labeled ×4commented ×1cross-referenced ×1

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

Error Message

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.

Root Cause

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

Fix Action

Fixed

PR fix notes

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

Description (problem / solution / changelog)

Note: This PR targets Rodriguespn/codex (a fork). The intended upstream destination is openai/codex. See issue openai/codex#23487.

Summary

  • Adds --scoped / -s to codex mcp add
  • When set, resolves the nearest git root (falls back to CWD) and writes the server entry into <root>/.codex/config.toml instead of ~/.codex/config.toml
  • Creates .codex/ directory automatically if absent
  • Success message says Added project-scoped MCP server '<name>' to <path>. so the destination is unambiguous

Motivation

Other agent CLIs already ship this flag:

  • Claude Code (--scope project) — docs
  • Gemini CLI (-s local) — docs

Codex already reads project-scoped servers from .codex/config.toml but codex mcp add only ever writes to the global ~/.codex/config.toml, forcing users to find and hand-edit the per-project file.

Changes

codex-rs/cli/src/mcp_cmd.rs

  • AddArgs: new scoped: bool field (--scoped / -s)
  • run_add: when scoped, determines the project root via a simple .git-walk and uses <root>/.codex/ as the target config folder (same load_global_mcp_servers + ConfigEditsBuilder::new pair, just pointed at a different directory)
  • find_project_root_for_scoped_config(): walks cwd.ancestors() for .git; returns cwd if none found

codex-rs/cli/tests/mcp_add_remove.rs

  • add_scoped_writes_to_project_dot_codex — stdio server, verifies project config written and global untouched
  • add_scoped_short_flag_works — short -s alias
  • add_scoped_without_git_falls_back_to_cwd — no .git, uses CWD
  • add_scoped_http_server_writes_to_project_dot_codex — streamable-HTTP variant

Changed files

  • codex-rs/cli/src/mcp_cmd.rs (modified, +44/-3)
  • codex-rs/cli/tests/mcp_add_remove.rs (modified, +139/-0)

Code Example

# 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
RAW_BUFFERClick to expand / collapse

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)

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…
#conversation history#tool integration#LLM response#prompt template#agent execution

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING