Blog / How agents load MCP tools

Claude Code can't see your MCP tools? Check the proxy and --tools settings first

For the basics (adding a server, scopes, auth) see the official docs. This page covers only the gotchas we hit, with numbers.

Leonid Bugaev · Published 21 Oct 2026

Basics first: Claude Code MCP documentation.

What each setting did

Claude Code 2.1.301 with a 99-tool mock server, prompt “say hi”, first-request input tokens:

“Off” means every MCP tool definition was in every request. Your tools are all visible then, but heavy; with “on”, they're visible by name only. See Claude Code tool search, seen from the wire.

Quick checks

1. Is the server connected? Check the app's MCP status before anything else.
2. Any custom ANTHROPIC_BASE_URL, proxy or gateway? Try ENABLE_TOOL_SEARCH=true.
3. Restricting built-in tools? Keep ToolSearch in the list.
4. Comparing runs or running evals? Measure the first request against a default run, so your lab matches your users.
5. Other apps: a project server in an untrusted folder was dropped silently by Grok Build in headless mode.

When it's the model, not the setup

If the tools are listed but the agent doesn't pick them, it's discovery: the model chose from names, or the user didn't name your product. See when the agent doesn't recognise your server and name tools the way users talk.

Go deeper: Capture what your agent sends, How Codex finds MCP tools, MCP tool-list token calculator.

Back to how agents load MCP tools.

How we measured

• Claude Code 2.1.301, 16 Oct 2026, a mock serving a recorded 99-tool list, single runs per config, first-request input from the app's own usage; tool search state confirmed from captured request bodies and debug logs.
• Single runs: settings behaviour, not rates. Versions change; re-check after updates.