Per-agent MCP server scoping: allow subagents to opt out of inherited MCP servers

What version of Codex CLI is running?

codex-cli 0.125.0

What subscription do you have?

Plus

Which model were you using?

gpt-5.5

What platform is your computer?

Linux 6.17.0-22-generic x86_64 x86_64

What terminal emulator and version are you using (if applicable)?

WezTerm 20260331-040028-577474d8

What issue are you seeing?

When a parent session has MCP servers configured (either globally in ~/.codex/config.toml or at project level), all spawned subagents
inherit them. There is currently no documented way for a custom subagent to disable or override this inheritance.

Our environment has 6 subagents, but only 1-2 of them actually need MCP access. The remaining agents (report generation, environment
maintenance, diagram building, read-only audit) work exclusively with local files. Despite this, every subagent spawn waits for all MCP
servers to start — including built-in ones like codex_apps — adding ~20-30 seconds of overhead per spawn with no benefit.

What we tried:

• Setting mcp_servers = {} in the agent TOML → inherited servers still load
• The subagents documentation states that mcp_servers "inherit from the parent session when you omit them" but provides no syntax for

explicitly clearing or restricting inheritance

Requested feature:

1. Allow mcp_servers = {} (or similar) in agent TOML to explicitly disable all inherited MCP servers for that agent
2. Alternatively, support an allowlist/blocklist model: mcp_servers.inherit = false or mcp_servers.exclude = ["codex_apps", "proceset"]
3. Document the inheritance override behavior either way

Impact:

• Faster subagent startup (skip unnecessary MCP connections)
• Better security posture (read-only audit agent shouldn't have write MCP tools)
• Reduced resource consumption for agents that don't need external tool access

Environment: Codex CLI, 6 custom subagents, 1 stdio MCP server (69 tools), codex_apps built-in

What steps can reproduce the bug?

1. Create ~/.codex/config.toml with a global MCP server (or have codex_apps built-in)
2. Create a custom subagent in .codex/agents/sesrep.toml that does NOT need MCP access
3. Add mcp_servers = {} to the agent TOML, expecting it to disable inherited servers
4. Spawn the subagent: "Use sesrep. Generate a report."
5. Observe: the subagent still shows "starting mcp servers: (1/2): codex_apps" and waits for all inherited MCP servers to initialize,

despite the explicit empty override

1. The inherited MCP tools are also visible to the subagent, even though its contract does not require them

What is the expected behavior?

When a custom subagent explicitly sets mcp_servers = {} in its TOML config, it should spawn without loading any MCP servers — neither
inherited from the parent session nor built-in ones like codex_apps.

Expected startup output: no "starting mcp servers" step.
Expected tool access: only Codex built-in tools (file read/write, shell), no MCP tools.
Expected startup time: near-instant, without 20-30 sec MCP initialization overhead.

Additional information

Documentation reference: https://developers.openai.com/codex/subagents states that mcp_servers "inherit from the parent session when you omit them" but provides no syntax or guidance for explicitly clearing or restricting this inheritance.

This is not just a performance issue — it also affects security posture. Our read-only audit agent (sandbox_mode = "read-only") still
inherits write-capable MCP tools like execute_graphql and create_script, which contradicts the principle of least privilege.

Workaround attempted: setting approval_mode = "approve" on dangerous tools at the parent level, but this is defense-in-depth, not proper
scoping.