feat: add support for per-profile MCP servers

[yaroslavyaroslav]

trafficstars

What

• Adds optional mcp_servers to profiles.<name> in config.
• Merges profile‑scoped servers into the global mcp_servers when that profile is active.
• Top‑level entries take precedence on key conflicts.
• Updates docs and adds a unit test.

Backwards Compatibility

• No breaking changes:
  • Existing configs with only top-level mcp_servers continue to work.
  • Profile mcp_servers are optional.
  • No changes to sandbox env vars or unrelated behavior.

Usage Example

[mcp_servers.global-tools]
command = "npx"
args = ["-y", "global-mcp"]

[profiles.o3]
model = "o3"

[profiles.o3.mcp_servers.project-tools]
command = "npx"
args = ["-y", "project-mcp"]

Affected Crates

• codex-core (implementation + tests)
• docs (configuration guide)

Closes #3023.

[yaroslavyaroslav]

@easong-openai @pakrym-oai @ae-openai @dylan-hurd-oai @edward-bayes

Guys could take a look at it, please if you'd have a minute?

[yaroslavyaroslav]

Guys, since #2720 is closed I encourage you to give a try to this one.

It covers this @bolinfest comment: https://github.com/openai/codex/pull/2720#discussion_r2308133509 by providing clear scope separation and clear MCP merge strategy by overriding global with local scopes if intersections appeared.

@dylan-hurd-oai

[yaroslavyaroslav]

@nornagon-openai bro, society is on the edge, tensions between countries arises, China is breathing down our neck and only you can save it by reviewing and merging this PR.

[0xdevalias]

I was surprised to find that profile scoped MCP servers wasn't already a thing. I feel like not having this currently is a bit of a security / privacy risk as well; as unless a user goes and manually comments out all the MCP servers each time; it's increasing the potential exposure in all of their codex sessions.

Allowing MCP servers to be defined per profile (or at the very least disabled globally and enabled per profile) would definitely be something worth prioritising getting merged sooner rather than later.

(Also, I haven't deeply reviewed the changes in this PR to see if it already does it, but from a UX perspective, something I tried today and was surprised to find didn't work was codex --profile foo mcp add bar -- baz. The help text for codex mcp add does explicitly say 'global' right now; but to make that profile scope aware would be a really nice UX tweak)

---

Edit: Summary from GitHub Copilot (gpt-5-mini) suggests that codex mcp add still only works globally for now. I wouldn't think this would be a blocker to this PR getting merged; but it would be a nice feature to add in a followup PR if not done here.

Short answer: This PR makes MCP servers profile‑aware at config‑load time (profile entries are merged into the runtime mcp_servers map when a profile is active), but it does not change the CLI persistence behavior of codex mcp add — that still only writes to the top‑level/global mcp_servers unless the CLI add command itself is changed in a separate PR.

Evidence from the PR:

• The code changes are limited to config loading and profile types:
  • config_profile.rs: adds an optional mcp_servers field to profiles so a profile can declare servers.
  • config.rs: during load it clones the top‑level mcp_servers and then inserts profile servers into that map, so the active profile’s servers are merged into the runtime mcp_servers (the inserted profile entries overwrite top‑level entries with the same key).
  • docs/config.md: documents per‑profile MCP servers and shows examples.
  • A unit test (test_mcp_servers_merge_from_profile) verifies the merge behavior and that the profile entry wins for conflicts.

No files modifying the codex mcp add command implementation were changed in this PR, so adding servers via the CLI still targets the top‑level/global config unless a separate change is made to the CLI to persist into a specific profile.

[kroath]

This is solid, not sure why this PR hasn't made it the main branch yet, it works flawlessly per my own testing thus far. Really helps having to comment out global MCP's and such, namely project scoped ones. Thanks for this.

[yaroslavyaroslav]

Dear @nornagon-openai, I mentioned you, but you still ain't reviewin'
I tagged mine handle, PR, and Slack at the bottom
I sent two reminders last Monday—you must not've got 'em
There probably was a CI pipeline glitch or somethin'
Sometimes I force-push branches too sloppy when I rebase 'em But anyways, forget it, what's been up, man? How's your daughter?

@bolinfest

[MiguelRipoll23]

Do I think adding profiles to MCP servers is a really good suggestion? Sure Is okay to spam contributors of the repository? Nope!

Just keep the PR open and be patient.

[yaroslavyaroslav]

Suddenly I came with that MCP sucks and custom cli's don't.

Thus I'm closing this. Anyone who want to continue to support this feel free to branch and create yours, most of the times update takes just to rebase it on main.

Gl hf.