Subagents do not inherit parent session's registered MCP tools #16475
Description
What version of Codex CLI is running?
codex-cli 0.117.0
What subscription do you have?
Pro
Which model were you using?
gpt-5.4
What platform is your computer?
Darwin 25.3.0 arm64 arm (macOS 26)
What terminal emulator and version are you using (if applicable)?
Ghostty 1.x (also reproduced inside Docker containers with no TTY)
What issue are you seeing?
Subagents spawned by a Codex session do not inherit the parent session's registered MCP tools, despite the documentation stating they should.
Setup: A Codex CLI interactive session has an MCP stdio server registered that exposes several mcp__team__* tools (spawn_worker, enqueue_task, get_status, etc.). The parent session can discover and call these tools successfully. When the parent session spawns an internal subagent (via Codex's own Agent tool), the subagent cannot see or call any of the mcp__team__* tools. The subagent behaves as if no MCP servers are configured.
| Context | MCP tools visible? |
|---|---|
| Parent session | Yes — all mcp__team__* tools listed and callable |
| Subagent spawned by parent | No — tools not listed, calls fail |
The MCP server process itself remains healthy throughout; the parent session can still use the tools after the subagent fails. This rules out a server crash or timeout.
What steps can reproduce the bug?
- Register a stdio MCP server in
~/.codex/config.toml:
[mcp_servers.team]
command = "/path/to/team-mcp-server"
args = []- Start a Codex CLI session and verify the MCP tools are available:
codex> /mcp
🔌 MCP Tools
• Server: team
• Status: enabled
• Tools: mcp__team__spawn_worker, mcp__team__enqueue_task, ...
-
Ask Codex to delegate a subtask that requires the MCP tools. Codex spawns an internal subagent.
-
The subagent reports that the
mcp__team__*tools are unavailable and cannot proceed. -
Return to the parent session — MCP tools still work fine there.
What is the expected behavior?
Per the Subagents documentation:
Optional fields such as
nickname_candidates,model,model_reasoning_effort,sandbox_mode,mcp_servers, andskills.configinherit from the parent session when you omit them.
Since the subagent does not override mcp_servers, it should inherit the parent session's MCP server registrations and have access to all the same MCP tools.
Additional information
Related issues:
- gpt-5.3-codex works in codex exec but fails in codex mcp-server subagent with same profile/auth #11927 — Similar inheritance failure: model auth configured in the parent doesn't propagate correctly to
codex mcp-serversubagents. Same class of "parent config not reaching child" bug. - Codex does not use MCP servers defined in config.toml. #3441, Codex fails to detect and use configured MCP gateway, repeatedly guessing binaries instead #5161 — MCP servers in
config.tomlnot detected at all. While those are about the parent session, they suggest the MCP registration/discovery plumbing has been fragile. - Support per-session MCP server configuration via exec options #9550 — Request for per-session MCP server configuration via
codex execflags (closed). The workaround suggested (-c 'mcp_servers.x.url=...') doesn't help here since the subagent is spawned internally, not viacodex exec.
Cross-ecosystem precedent:
- [Bug] Subagents not inheriting MCP tools from plugin-defined agents anthropics/claude-code#15810 — Identical pattern: subagents not inheriting MCP tools from the parent session. Confirmed as a bug, closed as duplicate of an internal fix.
- Subagent failed to use mcp tools after updating to 0.33.0 google-gemini/gemini-cli#22023 — Same regression in Gemini CLI after an update: subagents lost access to MCP tools.
This appears to be a common pitfall in AI CLI MCP implementations where the stdio MCP connection (or its tool registry) is scoped to the parent process and not forwarded when spawning child agent sessions.
Workaround: None known. Instructing the subagent to use the MCP tools via prompt engineering does not help since the tools are simply not registered in its session. The only mitigation is to avoid delegating MCP-dependent work to subagents entirely.