MCP Tool Search Auto Mode

When MCP tool descriptions exceed 10% of context window:

MCP Tool Search Auto Mode defers loading tool schemas until needed when their descriptions would consume more than 10% of available context.

How It Works

When MCP tool definitions exceed a 10% context threshold, Claude Code 2.1.7 stops loading them upfront. Instead, tools are discovered on-demand via a dedicated MCPSearch tool that queries the MCP servers at agent runtime. This preserves context window capacity for actual task work rather than tool inventory.

The mechanism is automatic: no user action required. For users with many or verbose MCP servers, this becomes a silent win. Users can opt out by adding MCPSearch to disallowedTools in .claude/settings.json.

What the Test Found

The test was not executed. The feature design and threshold (10% context) are documented, but no live runtime validation was performed to verify that tools are actually omitted upfront or that MCPSearch successfully surfaces them on-demand. The test plan was deferred because hitting the 10% threshold requires either many MCP servers or unusually verbose tool descriptions—uncommon in typical setups.

Why It Matters

As MCP adoption grows, agent context budgets become scarce. The auto-deferral strategy prevents tool inventory from fragmenting available context in a way that doesn't scale linearly. Heavy MCP users and organizations running many specialized tool servers benefit from this threshold.

Caveat

Until runtime-tested, the exact behavior—whether deferred tools are properly catalogued, whether MCPSearch latency is acceptable, whether the 10% threshold itself is correctly measured—remains unproven. The feature is specification-grade only.

Evidence & receipt

file2.1.7/tests/03-mcp-auto-search/TEST-RESULTS.md

◇ ed25519 receipt

idprimitive_5370440787c9d0886ca440d3

alged25519

pubkey9b87705613b1e2fd064d57fa75a6b679d2856ceafad6b1daa8f982493871b6dd

sig

0125018f147394dcc7699cd37c534a2071de11e569e71d07b3a5b448ac7e324ceda819808f56b31a3fe35441251f179bfc405bfe9698f825c08e512db9feff02

Signed with an ed25519 key held off the repo. Anyone can verify against the published public key; nobody without the secret key can forge it. Click verify: it recomputes the signature in your browser. The signature proves integrity and authorship of this exact content — not a third-party timestamp or that the underlying claim is objectively true. signedAt is when the @f3/attest pipeline ran, not when the work happened; the evidence refs carry the source dates.

Connected

instance-of Sandbox / Capability Class
introduces (in) 2.1.7 Test (2.1.7) Release
verifies (in) MCP Tool Search Auto Mode — runtime test Test

MCP Tool Search Auto Mode

Primitive

Kind	Primitive
Introduced	Claude Code 2.1.7
Class	Sandbox / Capability
Epistemic	inconclusive · runtime-test
Evidence	1 ref
Receipt	ed25519 · verifiable

Hands-on runtime test · Claude Code 2.1.7

Cite this page

Hunter, R. "MCP Tool Search Auto Mode." The Runtime Atlas. Content-addressed entity primitive_5370440787c9d0886ca440d3, ed25519-signed (integrity, not third-party timestamp). https://ryanhunter.io/atlas/e/2-1-7-mcp-auto-search

@misc{atlas-2-1-7-mcp-auto-search,
  title  = {MCP Tool Search Auto Mode},
  author = {Hunter, Ryan},
  note   = {The Runtime Atlas; entity primitive_5370440787c9d0886ca440d3; ed25519-signed for integrity},
  url    = {https://ryanhunter.io/atlas/e/2-1-7-mcp-auto-search}
}