The two `@deferred_model` refusals asserted only the exception type;
they now snapshot the message so a wording change is a deliberate diff
rather than a silent one. The first two wire-base tests gain the
provenance docstrings the rest of the file carries.
Every package init in the SDK resolves its submodules on attribute
access except four docstring-only leaves - mcp.os.posix, mcp.os.win32,
mcp.server.auth.handlers and mcp.server.auth.middleware - so a chain like
`import mcp; mcp.server.auth.handlers.token` stopped resolving even though
`mcp.client.stdio` and friends do. Give them the same lazy fallback, so
"attribute chains still resolve" is true without a footnote (explicit
imports remain the supported form), and pin one chain through each in the
ratchet.
`warm(everything=True)` warmed every protocol version's routing surface -
not "everything the SDK could ever build": the mcp package's own model
roots (mcpserver settings, tool/prompt argument models) belong to the mcp
layer that mcp-types cannot see, and they build during server construction
and tool registration anyway, which is startup work rather than
first-request work. Naming the flag `all_versions` says what it does; the
recommended host recipe is unchanged (`warm(version)` for the version the
transport negotiates).
WarmReport becomes a frozen dataclass instead of a NamedTuple, so a later
field addition does not disturb code that reads the existing fields, and
`mcp.warm` stays the very same function as `mcp_types.methods.warm` (pinned
by a test).
Completing a deferred model under the process-wide rebuild lock and then
letting pydantic generate its JSON schema outside it left one interleaving:
schema generation for a model reads the core schema of every model it
references, and for the mutually recursive wire JSON models (JSONObject /
JSONArray / JSONValue) a sibling could still be mid-build on another
thread, surfacing as a rare KeyError inside pydantic's schema generation
on some pydantic versions when many threads generated their first schema
of that family at once. No SDK-internal path did this (registration is
single-threaded), but user code may.
The generation now runs under the same lock as the build. Schema
generation is a cold path, so it just serializes with the deferred first
builds; steady state is unchanged. The concurrency ratchet also covers a
concurrent first schema over the recursive JSON family and the 2026 wire
package.
The two TypeError guards in deferred_model and plain warm() were
untested, and coverage.py counts the never-taken false arc of the
`if not TYPE_CHECKING:` guards around the lazy module attributes; that
arc belongs to the type checker, so declare it partial by design next
to the existing exclusion rules.
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.
Released pydantic (through 2.13) does not lock model_rebuild(), so the
first use of a defer_build model from several threads at once - sync tools
running on worker threads, or one client session per thread at process
start - could raise (AttributeError: __pydantic_core_schema__ and friends)
or install a stale validator instead of just building twice. A narrow
version of the same hazard already existed for the handful of models
that were incomplete at import; deferring every model made it reachable
from every entry point.
One process-wide RLock now serializes that one-time build. The
@deferred_model decorator becomes the single mechanism for a deferred
model root: it installs the lazy __signature__, the subclass hook, a
locked model_rebuild (public pydantic API; the extra wrapper frame is
accounted for via _parent_namespace_depth + 1) and a model_json_schema
that completes the class under the same lock before pydantic reads it
(pydantic re-reads the mock schema around a concurrent build).
MCPModel, WireModel and WireRootModel are decorated rather than
hand-writing the hook, and the remaining private deferred roots get the
decorator too, so no deferred model in the SDK builds outside the lock.
The decorator refuses a class that lacks defer_build or that defines its
own __pydantic_init_subclass__ (which it would otherwise replace).
Steady state is untouched: an already-built model never takes the lock.
A subprocess ratchet test races 8 threads over the monolith models, a
wire package, the JSON-RPC envelopes, the SDK's own models, the
module-level adapters and first schema/signature access, and asserts
zero exceptions (it fails without the lock).
- 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.
Set defer_build=True on MCPModel, the JSON-RPC envelope models and every
module-level TypeAdapter (the six union adapters in mcp_types, the message
adapter, and the four in mcp.client.session), so importing mcp_types no longer
pays for ~150 models' core schemas, validators and serializers: each is built
once, on first use. The explicit model_rebuild() calls go away (they force an
eager build), and the request-parameter models that carry InputResponses plus
the ContentBlock members are defined before their users so their field
metadata is complete without a first-use rebuild.
Under defer_build pydantic derives a model's __signature__ only when it
builds; a class-level lazy __signature__ (mcp_types._deferred, public pydantic
API only) completes the one-time build via model_rebuild() on first
inspect.signature() access, so introspection matches an eagerly-built model.
MCPModel and the generated wire bases install it for all their subclasses;
models deriving from BaseModel directly opt in with @deferred_model.
The generated _v2025_11_25 and _v2026_07_28 packages spent ~100-115 ms
each at import building pydantic core schemas, validators and serializers
for ~175 models per version, of which a connection touches only a handful.
Both generated bases now carry defer_build=True: WireModel, and a new
generic WireRootModel[T] the RootModel aliases derive from (deferring only
the object models made things slower, as the eager union roll-ups then
regenerated every deferred model's schema inline). The generator drops
codegen's trailing model_rebuild() epilogue and emits classes in dependency
order - failing if any class names a class defined later - so every
non-recursive generated class still exposes complete field metadata at
import. Building each model's validator now happens once, on first use.
Two dependencies still rode along with every `import mcp.server*` for
features most servers never use: the OAuth provider models (via
mcp.shared.auth and urllib.parse, ~10 ms) were imported by the
access-token leaf only for a return annotation and by request_state for
principal decomposition, and cryptography (~10 ms, 20-odd modules) was
imported at request_state's module top for the built-in codec.
The access-token module now spells its return type through the lazy
mcp.server.auth namespace and imports no OAuth model; request_state
resolves the provider's principal_components and the AEAD/KDF primitives
through cached loaders on first use (a codec is built by MCPServer(), so
that is where cryptography now loads - once, at construction, never per
request). The import-cost ratchet adds cryptography to the banned set of
every transport-agnostic server entry point and pins where its deferred
load lands.
Moving the HTTP transport and auth imports under TYPE_CHECKING made
typing.get_type_hints() raise NameError on public methods it used to
resolve on: MCPServer.streamable_http_app / sse_app / run_sse_async /
run_streamable_http_async / session_manager and Server.streamable_http_app
/ session_manager (EventStore, TransportSecuritySettings,
StreamableHTTPSessionManager, AuthSettings, OAuthAuthorizationServerProvider,
TokenVerifier were typing-only names in real annotations).
Two of those types get web-framework-free homes so the server modules can
import them for real without loading starlette: the resumability contract
(EventStore, EventMessage, EventCallback, EventId, StreamId) moves to
mcp.server.event_store, and mcp.server.transport_security keeps only the
pydantic TransportSecuritySettings while its starlette middleware moves
beside the transports. Both old import paths keep working with the same
objects. The session manager and the OAuth annotations are spelled through
the lazy mcp.server namespace instead (the trick already used for
Client.server), so they evaluate on demand and MCPServer stops importing
the OAuth provider stack at module load. The starlette-owned annotations
of the app builders (Starlette, Route, Request/Response) stay typing-only;
get_type_hints on those methods needs starlette's names supplied by the
caller.
Three implementations of lazy module attributes had grown: the
hand-rolled __getattr__/__dir__ in mcp/__init__.py, the submodule
fallback factory used by the four package inits, and a one-name
__getattr__ in mcp.server.elicitation. They shared two problems.
An unconditional module-level __getattr__ is visible to type checkers,
so pyright typed every misspelled `mcp.<name>` (and `mcp.client.<name>`,
...) as `object` instead of reporting it. And the submodule fallback ran
a filesystem find_spec on every attribute miss and speculatively imported
whatever matched, so a name sweep (cloudpickle's whichmodule, hasattr
probes) could import real submodules as a side effect, while
dir(mcp.client) no longer listed submodules it would happily resolve.
mcp.shared._lazy.lazy_module_attrs now serves all of them: lazy exports
(a `(module, attr)` pair or a zero-argument loader, resolved once and
cached in the namespace) plus known submodules (an explicit set, or the
package's real submodules listed once on first need). A miss is a plain
AttributeError with no search and no import, and __dir__ reports the
exports and submodules. Every caller binds the pair under
`if not TYPE_CHECKING:`, so attribute typos are pyright errors again
while the TYPE_CHECKING mirrors keep the real names typed. The
mcp.server.auth package gets the same fallback so qualified annotations
such as `mcp.server.auth.provider.TokenVerifier` resolve on demand.
The elicitation gate's wire-schema type is resolved through the same
mechanism from a cached accessor, so validating rendered schemas no
longer re-executes the wire-package import on every call.
typing.get_type_hints(Client) raises TypeError on CPython 3.10 for any
dataclass using KW_ONLY (a stdlib bug fixed in 3.11), which has nothing to
do with the SDK and turned the test red on the 3.10 CI cells. Probe
Client.__init__ instead: it evaluates the same qualified mcp.server
annotation on every supported version.
tests/test_import_guards.py runs every check in a fresh interpreter and pins
the module footprint each entry point is allowed to have: `import mcp` is a
lazy namespace, client entry points never load the server or web stack (and
httpx2 only for the HTTP transports), transport-agnostic server entry points
never load starlette / sse_starlette / uvicorn / opentelemetry / httpx2, and
the wire-schema packages load only when their protocol version is used.
A positive parametrized case imports every documented module as the first
import of a fresh process, warning-free, so the lazy resolution can never
grow an import-order dependency.
The earlier per-file fresh-interpreter probes are folded into this module,
which is now the single home for import-graph assertions.
Its module-level import moved into the validation function that uses it, so
the attribute would otherwise disappear from the module namespace. Resolve it
on first access via a module-level __getattr__ (and keep it in dir()) so
existing references to mcp.server.elicitation.PrimitiveSchemaDefinition keep
working without reintroducing the import at module load.
mcp_types.methods imported both generated wire packages (_v2025_11_25 and
_v2026_07_28, roughly 200 pydantic models each) at module import solely to
fill the surface maps' values, although a connection negotiates exactly one
protocol version and nothing reads a value at import time.
The map rows now record the wire type's attribute name; the package a row
lives in follows from the key's protocol version and is imported by a cached
lookup on the first row read, then cached per row. The public maps stay
MappingProxyType objects over the resolved rows (same protocol, repr and
equality as before), so importing mcp_types.methods - and therefore mcp,
mcp.types and every entry point above them - no longer builds any wire
package; the first message parsed for a version builds that version once.
The elicitation module's single wire-schema import moves into the function
that uses it for the same reason.
The method body had been marked `# pragma: no cover` (widened further once
httpx2 moved into the method). Exercise it against an httpx2 MockTransport
instead, covering both the response body and the raise_for_status path, and
drop the pragma.
Making the server stack a typing-only import in the client module left
the `Client.server` annotation naming `Server` / `MCPServer`, which
`typing.get_type_hints` can then no longer evaluate: string annotations
are evaluated against the module dict, so a module-level `__getattr__`
would not be consulted either.
Spell the annotation through the `mcp.server` namespace instead. Evaluating
the hints then walks the lazy `mcp` package, which imports `mcp.server` at
that moment only; `import mcp.client` stays free of the server stack and the
evaluated hint is the same union of classes as before. The package's
TYPE_CHECKING mirror now also lists the subpackages that its `__getattr__`
resolves on first access, so type checkers see the same chains.
The streamable-HTTP client transport (httpx2) is now imported when the
first URL Client is constructed instead of at import time, so a stdio-only
client (or a bare `import mcp.client`) never loads it. Tests cover the
resulting import contract: the client entry points load neither the
server stack nor httpx2 until they are used, and the package's lazy
server-side re-exports still resolve to their defining objects.
The test that patched `mcp.client.client.streamable_http_client` now
patches the transport at its defining module.
Adds a small PEP 562 __getattr__ factory (mcp.shared._lazy_submodules) and
installs it on the four packages, so attribute chains that used to resolve only
because the top-level package imported everything eagerly - e.g.
import mcp; mcp.client.stdio.stdio_client - keep resolving now that the mcp
package is lazy: touching pkg.name imports the submodule pkg.name if it exists,
raising AttributeError otherwise and surfacing a submodule's own missing
dependency as its real ImportError.
`import mcp` used to import the protocol types plus the entire client and
server stacks (in-memory transport, lowlevel server, HTTP transports, otel,
auth) just to bind the names in `mcp.__all__`.
Each export is now resolved from its home module by a module-level
`__getattr__` on first access and cached in the package namespace; the
old eager import block is mirrored name-for-name under `TYPE_CHECKING`
so type checkers and the docs generator see the same bindings.
`__all__`, `dir(mcp)`, `from mcp import *`, object identity and the
`mcp.types` submodule binding are unchanged.
A bare `import mcp` no longer loads pydantic, mcp_types or any mcp
submodule; each entry point pays only for what it uses.
Python's $ with re.match also matches just before a single trailing newline, so tool-name validation accepted "name\n" and UriTemplate.parse accepted varnames like "foo\n". Switch both checks to re.fullmatch.
Closes#3084
Max Isbey