Agent Plugin MCP tools are silently hidden after the global schema budget is exhausted

What version of the Codex App are you using (From “About Codex” dialog)?

Version 26.903.61454 (embedded Codex runtime 0.153.4)

What subscription do you have?

ChatGPT Pro

What platform is your computer?

Darwin 25.5.0 arm64 arm

What issue are you seeing?

MCP servers contributed by an Agent Plugin initialize and authenticate successfully, but most or all of their tools are silently omitted from the model-facing tool inventory.

I reproduced this with a private internal Agent Plugin in a fresh gpt-5.6-sol Codex Desktop task. The plugin name, repository, and organization-specific configuration have been omitted.

The App Server reported the following MCP tool inventories:

MCP server	Tools reported by the server	Tools exposed to the task
Datadog	27	17
Figma	41	1
Mixpanel	64	0
Sentry	9	0

The affected Mixpanel server is healthy:

• OAuth authentication succeeds.
• MCP initialization succeeds.
• The server reports version 3.3.0.
• Its advertised capabilities include tools, resources, and prompts.
• Generic list_mcp_resources succeeds and returns five resources.
• The App Server can retrieve all 64 tool definitions.

However, none of the 64 Mixpanel tools are callable by the model. There is no startup error, warning, or explanation in the UI. From the user’s perspective, the plugin is installed and connected but does not work.

What steps can reproduce the bug?

1. Install an Agent Plugin that contributes several MCP servers whose combined tool definitions exceed 64,000 bytes. A server with one or more tool definitions larger than 8,000 bytes also demonstrates the per-tool limit.

2. Authenticate the contributed MCP servers.

3. Restart Codex Desktop and open a fresh Code Mode task using gpt-5.6-sol.

4. Confirm through MCP status or App Server diagnostics that the servers initialize and that tools/list succeeds.

5. Ask Codex to invoke a tool from a server appearing later in the Agent Plugin MCP tool inventory, such as Mixpanel or Sentry.

6. Observe that the server’s tools are absent from the model-facing inventory even though the server is connected and its resources may still be accessible.

For the affected setup, the serialized tool-definition sizes reported by diagnostics were approximately:

MCP server	Tools	Total serialized definition size
Datadog	27	77,340 bytes
Figma	41	90,397 bytes
Mixpanel	64	278,781 bytes
Sentry	9	26,326 bytes

Eight individual Mixpanel definitions were also larger than 8,000 bytes. The largest were approximately:

• Create-Experiment: 27,892 bytes
• Update-Experiment: 27,733 bytes
• Create-Metric: 26,588 bytes
• Update-Metric: 21,061 bytes
• Get-Experiment: 17,530 bytes
• Run-Query: 11,687 bytes
• Get-Metric: 11,062 bytes
• Display-Query: 9,018 bytes

These sizes are included as diagnostic serialized sizes; the exact internal model_spec_bytes calculation may differ slightly.

What is the expected behavior?

An installed and successfully connected Agent Plugin should provide a usable path to its enabled MCP tools.

At least one of the following should happen:

1. Tools that exceed the static schema budget should be deferred and discoverable through tool_search instead of becoming unreachable.

2. The aggregate budget should be scoped per plugin or per MCP server rather than silently allowing earlier servers to consume the budget for unrelated later servers.

3. Codex should show a clear diagnostic containing:

   • the affected plugin and MCP server;
   • the number of exposed and hidden tools;
   • whether the per-tool or aggregate limit was exceeded;
   • the applicable byte limits;
   • remediation such as enabled_tools configuration.

4. Plugin installation or startup should warn when its declared MCP tool set cannot be exposed under the current limits.

Selection should also be deterministic and should not depend on MCP discovery order.

Additional information

The behavior appears to come from the Agent Plugin runtime boundaries added in PR #37027:

https://github.com/openai/codex/pull/37027

In Codex rust-v0.153.4, the relevant constants are:

const MAX_AGENT_PLUGIN_MCP_SPEC_BYTES: usize = 8_000;
const MAX_AGENT_PLUGIN_MCP_TOTAL_BYTES: usize = 64_000;

Source:

https://github.com/openai/codex/blob/rust-v0.153.4/codex-rs/core/src/mcp_tool_exposure.rs#L17-L18

The exposure logic marks an Agent Plugin MCP tool as ToolExposure::Hidden when either its individual definition exceeds 8,000 bytes or the shared aggregate Agent Plugin budget would exceed 64,000 bytes:

https://github.com/openai/codex/blob/rust-v0.153.4/codex-rs/core/src/mcp_tool_exposure.rs#L113-L135

The aggregate counter is shared across Agent Plugin MCP tools, so one server can consume the budget and cause tools from other servers to disappear. This is especially surprising because the affected servers still appear connected and continue exposing MCP resources.

The configuration reference documents enabled_tools and disabled_tools, but does not document these schema limits or explain how to diagnose tools hidden by them:

https://learn.chatgpt.com/docs/config-file/config-reference

Related but distinct issues:

• #32101 — ToolSpec::ToolSearch is converted to an empty definition in Code Mode.
• #33608
• #30922 and #38342 — broader reports of connected MCP tools being absent.

The primary problem in this report occurs before tool discovery: the tools are classified as Hidden. Therefore, fixing Code Mode’s tool_search exposure alone would not make these tools reachable.

Start in codex-rs/core/src/mcp_tool_exposure.rs, especially MAX_AGENT_PLUGIN_MCP_SPEC_BYTES, MAX_AGENT_PLUGIN_MCP_TOTAL_BYTES, and the exposure logic around lines 113-135. Compare the hidden-tool classification with the reported per-server and aggregate sizes, then inspect the configuration reference for enabled_tools and disabled_tools. Done should make affected tools reachable or clearly diagnose why they are hidden, with deterministic behavior across MCP discovery order.