codex - 💡(How to fix) Fix Codex bug: MCP servers load successfully but their tools aren't exposed to the model [2 comments, 3 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#20771Fetched 2026-05-03 04:45:48
View on GitHub
Comments
2
Participants
3
Timeline
7
Reactions
0
Author
Timeline (top)
labeled ×3commented ×2closed ×1unlabeled ×1

A user-defined MCP server configured under [mcp_servers.<name>] in ~/.codex/config.toml is spawned correctly and completes the MCP handshake (verified in logs), but the Codex session's tool list shown to the model contains only Codex-managed plugins (github, vercel, google-calendar, notion). The user-defined server's tools never appear, so the model can't invoke them.

Root Cause

A user-defined MCP server configured under [mcp_servers.<name>] in ~/.codex/config.toml is spawned correctly and completes the MCP handshake (verified in logs), but the Codex session's tool list shown to the model contains only Codex-managed plugins (github, vercel, google-calendar, notion). The user-defined server's tools never appear, so the model can't invoke them.

Fix Action

Workaround

None found. [plugins.*] entries work; [mcp_servers.*] entries connect but are unusable from the agent's perspective.

Code Example

[mcp_servers.agent-state]
command = "bash"
args = ["/Users/<user>/.codex/mcp-wrappers/agent-state.sh"]

---

level=TRACE target=rmcp::service
serve_inner: new event evt=PeerMessage(Response(JsonRpcResponse {
  jsonrpc: JsonRpcVersion2_0,
  id: Number(1),
  result: ListToolsResult(ListToolsResult {
    meta: None,
    next_cursor: None,
    tools: [
      Tool { name: "event_log", title: None, description: Some("..."), ... },
      // ...13 more tools
    ]
  })
}))
RAW_BUFFERClick to expand / collapse

Codex bug: MCP servers load successfully but their tools aren't exposed to the model

Suggested title for the issue:

MCP servers configured in [mcp_servers.X] load successfully but their tools are not surfaced to the model in the session

Suggested repo: openai/codex


Description

A user-defined MCP server configured under [mcp_servers.<name>] in ~/.codex/config.toml is spawned correctly and completes the MCP handshake (verified in logs), but the Codex session's tool list shown to the model contains only Codex-managed plugins (github, vercel, google-calendar, notion). The user-defined server's tools never appear, so the model can't invoke them.

Environment

  • codex-cli: 0.128.0
  • macOS: 14.x

Configuration

[mcp_servers.agent-state]
command = "bash"
args = ["/Users/<user>/.codex/mcp-wrappers/agent-state.sh"]

The wrapper resolves credentials from 1Password and execs a Node.js MCP server. Both work standalone — running the wrapper from a Terminal produces the expected agent-state-mcp ready stderr line and the server accepts tools/list requests.

Evidence the server loads + responds

From ~/.codex/logs_2.sqlite:

level=TRACE target=rmcp::service
serve_inner: new event evt=PeerMessage(Response(JsonRpcResponse {
  jsonrpc: JsonRpcVersion2_0,
  id: Number(1),
  result: ListToolsResult(ListToolsResult {
    meta: None,
    next_cursor: None,
    tools: [
      Tool { name: "event_log", title: None, description: Some("..."), ... },
      // ...13 more tools
    ]
  })
}))

So at the protocol layer, Codex received the catalog of 14 tools.

What the model sees

When prompted "list all available tools", the model reports only github, vercel, google-calendar, notion — the four [plugins.*] entries from config.toml. It does not mention the agent-state server or any of its 14 tools, and direct invocations like "call the tool named event_log" return "no such tool."

Expected behavior

Tools from [mcp_servers.X] entries should be visible alongside [plugins.X] tools in the model's tool registry.

Reproduction

  1. Configure any MCP server under [mcp_servers.X] in ~/.codex/config.toml (a public stdio MCP like the GitHub MCP or a tiny local hello-world MCP works for repro)
  2. Launch codex
  3. Verify in ~/.codex/logs_2.sqlite that rmcp::service recorded ListToolsResult for the server (proves it loaded)
  4. Inside the Codex session, ask the model to list available tools
  5. The user-defined server's tools are absent from the model's response

Hypothesis

Looks like there's a registration step between rmcp receiving the tool list and the session tool-registry being populated for the model. Either the registration call is missing, or the session's tool-list serialisation is filtering out non-plugin entries.

Workaround

None found. [plugins.*] entries work; [mcp_servers.*] entries connect but are unusable from the agent's perspective.

extent analysis

TL;DR

The issue can be resolved by investigating the registration step between rmcp receiving the tool list and the session tool-registry being populated for the model.

Guidance

  • Verify the rmcp::service logs to ensure the ListToolsResult is correctly received and processed.
  • Check the session's tool-list serialization to see if it's filtering out non-plugin entries.
  • Investigate the registration call between rmcp and the session tool-registry to ensure it's correctly handling [mcp_servers.X] entries.
  • Compare the handling of [plugins.X] entries to [mcp_servers.X] entries to identify potential differences in registration or serialization.

Notes

The issue seems to be related to the registration or serialization of tools from [mcp_servers.X] entries, and further investigation is needed to determine the root cause.

Recommendation

Apply a workaround by modifying the session's tool-list serialization to include non-plugin entries, if possible, or wait for a fix in a future version of codex-cli.

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…

FAQ

Expected behavior

Tools from [mcp_servers.X] entries should be visible alongside [plugins.X] tools in the model's tool registry.

Still need to ship something?

×6

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

Back to top recommendations

TRENDING

codex - 💡(How to fix) Fix Codex bug: MCP servers load successfully but their tools aren't exposed to the model [2 comments, 3 participants]