MCP Server Design · ~7 min

Found and Versioned

A great server nobody can find is dead weight. So is one that floods the window. Discoverability and token cost are two sides of the same budget — and they shape how your server evolves.

Tool schemas are injected into the model's context at startup. The GitHub MCP server alone has been measured at roughly 55,000 tokens across its 93 tool definitions; stacking servers can consume a third or more of a 200K window before any user input. Discovery is the mechanism that makes a large catalog affordable.

1 Eager vs. just-in-time loading

Modern hosts let each server choose whether its tools live in context from turn one (eager) or sit behind a tool-search step that loads them on first reference (just-in-time). Claude Code exposes this as alwaysLoad; the API has a per-tool defer_loading. Four signals decide:

Deferred loading preserves the prompt cache: deferred tool definitions append inline when discovered, so the cacheable prefix is untouched — unlike naively rebuilding the tool list per step, which busts the cache.

2 The silent failure: search-miss

JIT's failure mode is invisible. If your tool descriptions use jargon the model won't search for, the agent reports “no tool available” when one is right there.

3 Discovery scopes and version stability

Server definitions can live at user, project/workspace, and local scope. When the same name appears at multiple scopes, hosts apply most-specific-wins — the closest scope defining a name silently disables the outer ones. Two consequences for a server author:

• Name for intent. If a developer's github points at a private fork and the team's at the public registry, dedup silently disables one. Shadowing is for overrides of the same intent; parallel intents need distinct names.
• Version through descriptions and types, not tool names. Names should carry no version numbers (Lesson 3). When an upstream API gains a value, an enum breaks until redeploy — prefer thin string types on fast-churning fields so your surface stays stable across the agent's training gap.

The remote-vs-local choice from Lesson 1 also locks your auth path: remote forces OAuth, which forces the client-registration decision (CIMD vs. DCR), which shapes whether you need a credential vault. Sequence those decisions deliberately — each forecloses the next.