---
title: How Codex Finds MCP Tools: Code Mode and ALL_TOOLS
description: Codex doesn't send your MCP tools to the model. In code mode it filters ALL_TOOLS in JavaScript first; 6 of 40 live runs never found them. Wire capture.
canonical: https://spiritroom.app/blog/how-codex-finds-mcp-tools/
published: 2026-10-21
updated: 2026-10-21
---

> Markdown version of https://spiritroom.app/blog/how-codex-finds-mcp-tools/ for agents. Index: /llms.txt

[Blog](/blog/) / [How agents load MCP tools](/guides/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

**TL;DR**

- **Codex's first request has no MCP tool names in it.** In Codex 0.161 with its default code mode, the model got one `exec` tool with a 6,471-token description, and the word naming our server appeared nowhere.
- **The model has to search.** It wrote JavaScript to filter `ALL_TOOLS` by name and description. The first filter returned 56,619 tokens, truncated to 11,244; two narrower ones followed before the right call.
- **Sometimes it never searches.** On a 99-tool production server, Codex never reached the tools in 6 of 40 live runs (7–29%) and said no connector was available.
- **It costs about 40k tokens before the first call**, whatever the server does. On a 21-tool mock, Codex's median run was 78k–89k input tokens; Claude Code's was 20k–27k.
- **What helps:** the product name and users' words in tool names and descriptions, because that's what the filter matches, and instructions that say what the server is for, because Codex puts them in front of every tool description.
[What the model sees first](#first)[How the search works](#search)[When Codex never finds your tools](#miss)[What it costs](#cost)[What your server can do](#help)[How we measured](#how-we-measured)[FAQ](#faq)

## 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`.

User question**→**exec + ALL\_TOOLS hint**→**Model writes a filter**→**Reads matches**→**Calls tools.x() in JS

## 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.

One Codex turn on a 99-tool mock, 16 Oct 2026

| Step | What happened | Size |
| --- | --- | --- |
| First request | `exec` + namespaces, no MCP tool names | 15,383 tokens |
| Filter 1 | All tools matching the product name | 56,619 tokens, cut to 11,244 |
| Filters 2–3 | Narrower matches | 1,777 and 3,030 tokens |
| Call | The right tool, from JavaScript | — |
| Whole turn | 6 model requests | 137,344 input (120,576 cached), 331 output |

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](https://github.com/openai/codex/pull/17287) and [tool search for MCP by default](https://github.com/openai/codex/pull/29486), and an issue on [code mode omitting tool\_search](https://github.com/openai/codex/issues/32101). Check your version.

**Check whether Codex finds your tools.**

We run your users' jobs through Codex, Claude Code and the other apps they use, capture what each sends to the model, and report discovery rates, cost and fixes, with confidence ranges.

[Test your MCP →](/#contact)

## 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](/blog/agent-does-not-recognise-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](/blog/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](/blog/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?](/blog/do-agents-read-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](/blog/get-instructions-first-24-of-24/).
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](/guides/how-agents-load-mcp-tools/), [Claude Code tool search, seen from the wire](/blog/claude-code-tool-search-explained/), [Repeated calls in Codex](/blog/duplicate-tool-calls/).

## 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.

## FAQ

### How does Codex CLI discover MCP tools?

In Codex 0.161's default code mode, MCP tools are not sent to the model as tools. The model gets an exec tool for running JavaScript and is told to filter ALL\_TOOLS by name and description. It writes a filter, reads the matches, and then calls the tool from code.

### Why does Codex say no MCP connector is available?

Because the first request doesn't mention your server. If the model doesn't think to search ALL\_TOOLS for the user's question, it never sees your tools. That happened in 6 of 40 live runs on a 99-tool production server, and on vague requests in a mock test.

### Does Codex use tool\_search for MCP tools?

Not in the code-mode default we captured. Codex 0.161 with its default model sent no tool\_search tool; discovery went through JavaScript filters over ALL\_TOOLS. Public Codex issues and pull requests show this is changing between versions, so check yours.

### How many tokens does Codex use before calling an MCP tool?

About 40k in our mock tests, whatever the server did, because of the large exec description and the search step. In a captured run on a 99-tool server, the whole turn used 137,344 input tokens, most of it cached.

### Do Codex MCP server instructions reach the model?

Yes, but not in the first prompt. Codex prepends them to every tool description, so the model sees them only after it searches and reads tool descriptions.

**Check whether Codex finds your tools.**

We run your users' jobs through Codex, Claude Code and the other apps they use, capture what each sends to the model, and report discovery rates, cost and fixes, with confidence ranges.

[Test your MCP →](/#contact)

## Keep reading

- Up[How agent apps load MCP tools: what the model sees (guide)](/guides/how-agents-load-mcp-tools/)
- Related[When the agent doesn't know your MCP server is the right tool (“Which product do you mean?”)](/blog/agent-does-not-recognise-mcp-server/)
- Related[Why agents call the same MCP tool twice (13 of 40 runs) and how to stop it](/blog/duplicate-tool-calls/)
- Related[Claude Code tool search, seen from the wire: the model picks your tool from its name](/blog/claude-code-tool-search-explained/)
- Related[Do AI agents read your MCP server instructions? Tested in Claude Code, Codex, Grok and OpenCode](/blog/do-agents-read-mcp-server-instructions/)