Blog / How agents load MCP tools

How Codex finds your MCP tools: code mode, ALL_TOOLS and the search before the first call

You connect your MCP server to Codex, ask a question your server answers, and Codex says no connector is available. Your server is running and lists every tool. The reason is how Codex shows tools to the model: it doesn't, until the model goes looking.

Leonid Bugaev · Published 21 Oct 2026

What the model sees first

Most writing about Codex and MCP covers configuration: config.toml, transports, auth. What happens next is less documented. We captured Codex 0.161.0's traffic to the model with a process-scoped proxy, with a 99-tool mock server connected and every other server switched off.

The first request was 15,383 tokens and held only a few tool namespaces: an exec tool for running JavaScript, with a 6,471-token description, plus wait and a few built-ins. None of the 99 MCP tools were in it. The server's name appeared nowhere. The exec description told the model that some tools are deferred and that it can filter ALL_TOOLS by name and description.

How the search works

In the captured run, the model's first move was a JavaScript filter over every tool's name and description, matching the product name. That returned every tool from the server: 56,619 tokens, which Codex truncated to 11,244 before the model saw it. The model then ran two narrower filters (1,777 and 3,030 tokens of output) and called the right tool from code.

So the index Codex searches is your tool names and descriptions, through a regex the model writes. There was no tool_search tool and no ranking. Turning code mode off didn't bring classic tool search back for this model and account: the run failed with “code-mode host is disabled”. Codex's code is moving here, with pull requests on deferring MCP tools in code mode and tool search for MCP by default, and an issue on code mode omitting tool_search. Check your version.

When Codex never finds your tools

The search only happens if the model thinks of it. In live, read-only runs on a 99-tool production server, 8 everyday questions × 5 runs:

• Codex never reached the server's tools in 6 of 40 runs (95% range 7–29%). It said no connector was available and tried a browser instead. Across two rounds it was 8 of 80 (5–19%).
• When it did find them, it answered correctly in 34 of 34.
• Claude Code, which lists MCP tool names up front, found them in 40 of 40.

Vague requests are the worst case. On a mock, “Help me get more out of [product]” made Codex ask which product the user meant, with no call, in 2 of 2 runs with only a get_instructions tool and 1 of 1 with a hint in the instructions: the hint lives in places the model never reads before searching. More on this failure in when the agent doesn't recognise your MCP server.

What it costs

The search has a floor. In our mock tests, Codex used about 40k input tokens before the first call to the server, whatever the server did. On today's 21-tool mock, with a 1,730-token tool list, Codex's median run was 78,126 to 89,129 input tokens depending on the server version, against 20,249 to 26,960 for Claude Code on the same jobs. Both got every job right; see per-model MCP tool surfaces.

That floor is why a smaller tool list barely moves Codex's first request: adding all 99 tools of the production server added +0 tokens to it, against +1,715 for Claude Code. See how many MCP tools is too many.

What your server can do

1. Name things the way users ask. The model's filter is a regex over names and descriptions, usually built from the user's words or your product name. Put both in the first line of each description.
2. Say what the server is for in the instructions. Codex prepends server instructions to every tool description, so they arrive with every match. Keep them short: they're repeated per tool. See do agents read your MCP server instructions?
3. Keep descriptions compact. A broad filter returns every match in full; the more each description weighs, the sooner the output is cut.
4. Add a hint line to descriptions pointing to get_instructions. Once the model searches, it sees it. With the full recipe, Codex called it first in 24 of 24 mock runs. See make the agent read your playbook first.
5. Accept what you can't fix. Nothing your server sends is shown before the first search. If users phrase things vaguely, tell them to name the product.

Go deeper: How agent apps load MCP tools, Claude Code tool search, seen from the wire, Repeated calls in Codex.

How we measured

• Wire capture: Codex CLI 0.161.0 with its default model, ChatGPT login, 16 Oct 2026, 13:03–13:07 (UTC+3). A process-scoped proxy with a temporary certificate trusted only by the child process; headers redacted; sizes in o200k_base; per-request input from the provider's usage.
• Live runs: a 99-tool production MCP server, 8 read-only jobs × 5 runs, every call through a read-only allowlist proxy, 16 Oct 2026; a second round for the 8 of 80 figure.
• Mock runs: the 40k floor and vague-request behaviour from 232 runs on a mock of the same server, 18 Oct 2026; the 21-tool medians from 30 Codex runs on 21 Oct 2026.
• Limits: one Codex version and model. Codex's tool loading has changed between versions; re-check after updates.