The wire schemas load on the first message per protocol version and the
pydantic validators build on first use, which keeps imports fast but puts a
one-time bill on a process's first messages. A long-running host that
would rather pay that at startup than on its first request had only a DIY
recipe of model_rebuild() loops.
mcp_types.methods.warm(version=None, *, everything=False) is the supported
version: with no argument it builds the version-independent set (the
exported mcp_types models, the JSON-RPC envelopes and the routing union
adapters, ~50 ms); with a version it also imports that version's wire
package and builds the routing surface a connection at that version uses
(so its first messages then build nothing); everything=True covers every
known version. Model classes are always completed before the adapters
that reference them, so no schema is generated twice, and repeat calls
are no-ops. It returns a small WarmReport for logging and is re-exported
as mcp.warm. Nothing in the SDK calls it. The import-cost docs recipe now
uses it.
- AGENTS.md: state the import-cost exception to the imports-at-top rule,
listing which stacks stay off which import paths and pointing at the
ratchet test that enforces it.
- New docs page "Imports & startup time" (Advanced): what loads when, the
one-time first-use costs, and a tested prewarm recipe for hosts that want
the deferred work paid at startup.
- Migration guide: the lazy import graph, the incidental namespace bindings
that moved to their defining modules, and defer_build inheritance for user
subclasses of SDK models.
- What's new: one paragraph on imports paying only for what they use.
Max Isbey