docs/advanced/import-cost.md now states the size of every deferred bill (the
per-version wire package, the first HTTP app, the first span, cryptography,
the OAuth provider models, and the ~130 ms a fresh process pays once on its
first connection), and grows an FAQ: an installed pydantic plugin such as
logfire still loads at `import mcp.types` (PYDANTIC_DISABLE_PLUGINS is the
lever), __pydantic_complete__ reads False until first use, function-local
model subclasses keep the generic signature until first use, what to hand a
static bundler, and the get_type_hints waiver for the app builders.
AGENTS.md's import-cost bullets are corrected to match the code: only
mcp/__init__ resolves exports lazily while the other package inits resolve
submodules; cryptography and the OAuth provider models load with their
first user rather than at import; the wire packages also load for the first
rendered elicitation schema. The migration guide notes the removed
McpHttpClientFactory re-export from mcp.client.streamable_http.
- 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