Cut import and startup cost with deferred model builds and lazy imports

Every import path now pays only for what it uses, with no public API
added or removed:

- The protocol models (mcp.types / mcp_types, incl. the JSON-RPC
  envelopes and the generated per-version wire packages) build their
  pydantic validators on first use instead of at import (defer_build),
  through one shared private base class. First-use builds are
  serialised behind a single process-wide lock, since released pydantic
  does not make concurrent first use of a deferred model thread-safe;
  this also fixes a pre-existing concurrent-first-use failure that
  reproduces on main.
- `import mcp` binds the client/server names lazily on first attribute
  access (PEP 562) instead of importing both stacks eagerly, and the
  client no longer imports the server, so client entry points stop
  loading the server, the web stack, httpx2 and cryptography.
- The web application stack (starlette's app machinery, sse_starlette,
  uvicorn) loads with the app builders that use it, and each protocol
  version's wire package loads on the first message parsed for that
  version rather than both loading at import.

On the fresh-interpreter harness `import mcp` is ~0.4x of v1 (main is
~1.6x), the client entry points ~0.6x of v1, `import mcp.server.mcpserver`
~0.7x, and time-to-ready / stdio cold start land at parity with v1. RSS
after `import mcp` is 19 MiB (v1 43.5, main 57). Steady-state per-call
latency is unchanged.

Observable-but-incidental differences (removed incidental namespace
bindings, deeper submodules no longer imported as a side effect of a
bare `import mcp`, get_type_hints needing localns= for a documented set
of callables, pre-first-use introspection) are catalogued in
docs/migration.md; ratchet tests pin the import footprints and the
concurrent-first-use safety.

Author: maxisbey

AGENTS.md

@@ -45,7 +45,21 @@
 - IMPORTANT: All imports go at the top of the file — inline imports hide
   dependencies and obscure circular-import bugs. Only exception: when a
   top-level import genuinely can't work (lazy-loading optional deps, or
-  tests that re-import a module).
+  tests that re-import a module), plus the deliberate startup-cost seams
+  below — each of those local imports carries a why-comment; don't hoist them.
+- Startup-cost seams (pinned by `tests/test_import_footprint.py`, so a
+  hoisted import fails a test rather than review): `mcp/__init__.py` binds
+  the client/server names and `mcp.types` lazily; `mcp.client.client` never
+  imports the server, and imports the streamable-HTTP client (httpx2) only
+  for a URL; `mcp.server.elicitation` imports the 2025-era wire package inside
+  its schema-validation gate; the two server hubs (`lowlevel/server.py`,
+  `mcpserver/server.py`) import the HTTP web stack inside
+  `streamable_http_app()` / `sse_app()` / `custom_route()`; the auth context
+  accessor imports its `AuthenticatedUser` type inside the middleware
+  constructor; `HttpResource.read` imports httpx2 in the method; and
+  `mcp_types.methods` resolves each version's wire package
+  (`mcp_types._v20*`) on the first surface-map row read, never at import.
+  `docs/advanced/startup.md` states the user-facing contract.
 
 ## Testing
 

docs/advanced/index.md

@@ -11,6 +11,8 @@ layer is in the way:
   can *only* do on the low-level `Server`.
 * **[Extensions](extensions.md)** and **[MCP Apps](apps.md)**: the protocol's
   extension surface. Compose extension packages into a server, or write your own.
+* **[Startup cost](startup.md)**: what an import loads, and the one-time bills paid
+  on first use instead — for when you are measuring cold start.
 
 A few things you might reasonably look for here live where you'd actually use them
 instead:

docs/advanced/startup.md

@@ -0,0 +1,67 @@
+# Startup cost
+
+The SDK is arranged so a process pays only for what it actually uses, and pays for
+each thing once. Two rules produce that; both are occasionally observable, so they
+are written down here.
+
+## What an import loads
+
+`import mcp` loads the protocol types (`mcp_types`) and nothing else: no client, no
+server, no web stack, no HTTP client. The client/server names it exports (`mcp.Client`,
+`mcp.ClientSession`, `mcp.stdio_server`, ...) and `mcp.types` resolve their home
+module on first access and are then cached on the package, so `from mcp import Client`
+costs the client import exactly once, when you ask for it.
+
+Importing an entry point loads only its own side: a client entry point
+(`import mcp.client.stdio`) never imports the server stack or the HTTP client stack,
+which loads with your first URL-shaped `Client`; a server entry point never imports the
+client, and a transport-agnostic one (`mcp.server.stdio`, `MCPServer`, the lowlevel
+`Server`) never imports the HTTP web stack (starlette's app/request stack,
+`sse_starlette`, `uvicorn`) — that loads when you first build an HTTP app
+(`streamable_http_app()`, `sse_app()`, a custom route). Because these are import-graph
+promises, they are tested: adding an eager import that breaks one fails the suite.
+
+One introspection consequence: `typing.get_type_hints()` on the seven HTTP-app methods
+(`Server.streamable_http_app`, `Server.session_manager`, `MCPServer.streamable_http_app`,
+`MCPServer.sse_app`, `MCPServer.run_sse_async`, `MCPServer.run_streamable_http_async`,
+`MCPServer.session_manager`) raises `NameError`: their annotations name HTTP types that
+those modules import for type checkers only. Signatures, static typing, and calling the
+methods are unaffected; if you evaluate the hints at runtime, pass the types yourself, e.g.
+`typing.get_type_hints(MCPServer.sse_app, localns={"TransportSecuritySettings":
+mcp.server.transport_security.TransportSecuritySettings, "Starlette":
+starlette.applications.Starlette})`.
+
+## One-time first-use bills
+
+The generated wire types for each protocol version load with the first message a
+connection parses for that version, not at import — a connection negotiates one
+version, so a process loads that version's models (a few tens of milliseconds once)
+and never the other's. Protocol model validators are then built on a model's first use
+(validation, dumping, `model_json_schema()`), a few milliseconds once for the models a
+message touches; everything after is at full speed. There is no per-call cost.
+
+Reading whole surface maps in `mcp_types.methods` (`.values()`, `.items()`, spreading
+one into an extension map) loads both versions' wire types at that moment, and a
+server's first elicitation loads the wire types its schema gate validates against.
+
+If pydantic plugins are installed (`logfire`, for example) pydantic loads them at that
+first model build. When you are measuring or shaving cold start and don't use them,
+export `PYDANTIC_DISABLE_PLUGINS=__all__`.
+
+## Introspecting a model before its first use
+
+Because a model is built on first use, class-level introspection of a protocol model
+that nothing in the process has used yet reflects the not-yet-built state:
+`inspect.signature(Tool)` shows the generic `(**data)` initializer, and
+`Tool.__pydantic_complete__` is `False`. Using the model once, or calling
+`Tool.model_rebuild()`, resolves it; from then on introspection is identical to an
+eagerly-built model. Instances, validation, serialization, and schemas are unaffected.
+
+## First use from threads
+
+First-use builds are serialised across threads by one process-wide lock, so concurrent
+first use is safe. Two consequences worth knowing: generate schemas through the model's
+own `Model.model_json_schema()` (pydantic's module-level `pydantic.json_schema.model_json_schema(Model)`
+bypasses the serialisation), and don't `fork()` while another thread is mid-way through a
+model's first use — the child inherits the held build lock; use the model once first, or the
+`spawn` start method.

docs/migration.md

@@ -197,6 +197,26 @@ Both commands now pin the requirement to the version you are running
 (`mcp==<installed version>`). Source builds and other unpublished versions, which have
 nothing on PyPI to pin to, keep the unpinned form.
 
+### `import mcp` no longer imports the client and server stacks
+
+`import mcp` used to import the whole client and server stack (and with it starlette,
+uvicorn, httpx2, ...) as a side effect. It now imports only the protocol types; `Client`,
+`ClientSession`, `ClientSessionGroup`, `StdioServerParameters`, `stdio_client`,
+`ServerSession`, `stdio_server`, `InputRequiredRoundsExceededError`, and the `mcp.types`
+submodule are the same names and objects, resolved on first access. This is invisible
+unless code depended on the side effects:
+
+* `sys.modules` after `import mcp` no longer contains `mcp.client*`, `mcp.server*`, or
+  their dependencies. Import what you use.
+* Attribute chains from a bare `import mcp` still reach `mcp.types`, `mcp.client`,
+  `mcp.server`, and `mcp.os`, but a module the old package init imported for you needs its
+  own `import` before `mcp.client.stdio.<name>` works — for example `mcp.client.stdio`,
+  `mcp.client.session_group`, `mcp.client.sse`, `mcp.client.streamable_http`, and
+  `mcp.shared.memory`.
+* Client entry points (`mcp.client.stdio`, `from mcp import Client`, ...) no longer import
+  the server stack, and the HTTP client stack loads with your first URL-shaped `Client`
+  rather than at import. See [Startup cost](advanced/startup.md).
+
 ## Types and wire format
 
 ### `mcp.types` moved to the `mcp-types` package
@@ -640,6 +660,45 @@ JSONRPCError(jsonrpc="2.0", id=None, error=ErrorData(code=PARSE_ERROR, message="
 
 Delete any shim that accepted or synthesized null-id error responses. Code that assumed `error.id` was always a `str | int` must now handle `None`, and tests that pinned v1's rejection of `"id": null` now fail because validation succeeds.
 
+### Protocol models build their validators on first use
+
+The protocol models (`mcp.types` / `mcp_types`, including the JSON-RPC envelopes) now build
+their pydantic validators on a model's first use in the process instead of at import
+(`defer_build`), which is most of the SDK's startup cost. Validation, serialization, JSON
+schemas, and everything after a model's first use are unchanged (one wrinkle: `inspect.signature`
+on the `model_rebuild` / `model_json_schema` classmethods shows the SDK's evaluated annotations
+rather than pydantic's stringised type aliases — parameter names, kinds and defaults are
+identical). Two things are observable *before* a model's first use:
+
+* `inspect.signature(Model)` / `help(Model)` show pydantic's generic `(**data)` initializer
+  and `Model.__pydantic_complete__` is `False`. A few models (`CallToolRequest`,
+  `GetPromptRequest`, `ReadResourceRequest`, `SamplingMessage`, `ToolResultContent`) already
+  behaved this way; it now applies to all of them until first use. Use the model once, or call
+  `Model.model_rebuild()`, when you need the resolved signature earlier.
+* Every model's MRO gains one private base (`mcp_types._wire_base.DeferredModel`) between it
+  and `pydantic.BaseModel`, visible only to code that walks `__mro__`.
+* The module-level parse adapters (`client_request_adapter`, ..., `jsonrpc_message_adapter`)
+  are instances of a private `TypeAdapter` subclass (`mcp_types._wire_base.DeferredAdapter`) so
+  their first-use build takes the same lock; `isinstance(adapter, TypeAdapter)` and every
+  documented `TypeAdapter` operation are unchanged.
+
+The one-time build cost moves from `import` to each model's first use — a few milliseconds
+for the first message a connection parses; see [Startup cost](advanced/startup.md).
+
+The per-version wire types behind the `mcp_types.methods` surface maps
+(`CLIENT_REQUESTS`, `SERVER_RESULTS`, ...) go further: a version's wire types load on the
+first row read for that version — in practice with the first message a connection parses —
+rather than at `import mcp_types.methods`, so a process loads only the protocol version it
+negotiates. Every documented map operation is unchanged (lookup, `in`, iteration, `len`,
+`get`, `==`, spreading into an extension map, `repr`); the whole-map reads among them
+load both versions at that moment. Three obscurities are observable: the maps'
+non-`Mapping` dict extras are gone (`.copy()`, `|`, `reversed()`, and `keys()`/`values()`/
+`items()` return view objects), the internal `mcp_types.methods.v2025`/`v2026` attributes
+are import-free stand-ins rather than the wire-package modules, and the wire types are no
+longer bound in `mcp.server.elicitation`. Import the generated packages
+(`mcp_types._v2025_11_25`, `mcp_types._v2026_07_28`) directly if you need them, though the
+version-free `mcp.types` models remain the supported surface.
+
 ## MCPServer (formerly FastMCP)
 
 ### `FastMCP` renamed to `MCPServer`
@@ -877,6 +936,27 @@ Beyond the constructor parameters that moved to `run()`/`streamable_http_app()`
 
 Only private attributes moved: `mcp._mcp_server` is now `mcp._lowlevel_server` (see [Registering lowlevel handlers from `MCPServer`](#registering-lowlevel-handlers-from-mcpserver)), and `_session_manager` now lives on that lowlevel `Server`. Prefer the public `mcp.session_manager` property to either.
 
+### The server modules no longer import the HTTP stack
+
+`mcp.server.lowlevel.server` and `mcp.server.mcpserver.server` used to import the Streamable
+HTTP / SSE stack at module top, so any server — including a stdio one — loaded starlette,
+`sse_starlette`, and `uvicorn` at import. That stack now loads inside `streamable_http_app()`,
+`sse_app()`, and `custom_route()`, their only users; a stdio server never pays for it. Two
+things follow:
+
+* The HTTP names that were only incidentally reachable as attributes of those two modules
+  (`Starlette`, `Route`, `Mount`, `EventStore`, `TransportSecuritySettings`,
+  `StreamableHTTPSessionManager`, `SseServerTransport`, and the auth middlewares/routes) are no
+  longer bound there. Import them from their homes (`starlette.applications`,
+  `mcp.server.streamable_http`, `mcp.server.transport_security`,
+  `mcp.server.streamable_http_manager`, `mcp.server.sse`, `mcp.server.auth.middleware.*`,
+  `mcp.server.auth.routes`).
+* `typing.get_type_hints()` on the HTTP-app methods (`streamable_http_app`, `sse_app`,
+  `run_sse_async`, `run_streamable_http_async`, and the `session_manager` properties) raises
+  `NameError`, because their annotations name types those modules import for type checkers only;
+  pass them yourself as `localns={...}` if you evaluate the hints at runtime. See
+  [Startup cost](advanced/startup.md).
+
 ### `MCPServer.get_context()` removed
 
 `MCPServer.get_context()` has been removed. Context is now injected by the framework and passed explicitly — there is no ambient ContextVar to read from.
@@ -2056,6 +2136,21 @@ result = await client.call_tool("long_running_task", {}, progress_callback=on_pr
 
 Also drop `execution=ToolExecution(taskSupport=types.TASK_REQUIRED)` from tool definitions: the `TASK_REQUIRED` / `TASK_OPTIONAL` / `TASK_FORBIDDEN` constants are gone from `mcp.types` (`ToolExecution.task_support` takes the plain `"required"` / `"optional"` / `"forbidden"` literal), and no v2 client or server reads the field.
 
+### `mcp.client.client` no longer imports the server stack
+
+The client module no longer imports the server, so names that were only incidentally
+reachable as attributes of `mcp.client.client` (`Server`, `MCPServer`, `modern_on_request`,
+`InMemoryTransport`, `streamable_http_client`) are no longer bound there. Import and
+`mock.patch` them at their own modules: `mcp.server.Server`, `mcp.server.mcpserver.MCPServer`,
+`mcp.server.runner.modern_on_request`, `mcp.client.streamable_http.streamable_http_client`
+(the in-memory transport is constructed for you by `Client(server)`).
+
+One introspection consequence: `typing.get_type_hints(mcp.Client)` (and of `Client.__init__`)
+now raises `NameError`, because the `server` field annotation names imports that exist only for
+type checkers. Static typing, `inspect.signature`, `dataclasses.fields`, and every documented
+use are unaffected; if you do evaluate those hints at runtime, pass
+`localns={"Server": mcp.server.Server, "MCPServer": mcp.server.mcpserver.MCPServer}`.
+
 ## Transports
 
 Server-side transport entry points (`stdio_server()`, `SseServerTransport`, `StreamableHTTPSessionManager`) keep their v1 import paths and signatures (see [Lowlevel `Server`: what did not change](#lowlevel-server-what-did-not-change)), so the sections below are client-side apart from [`stdio_server` keeps the protocol streams on private descriptors](#stdio_server-keeps-the-protocol-streams-on-private-descriptors); the other server-side transport changes ([lifespan entered once](#streamable-http-lifespan-now-entered-once-at-manager-startup), the [4 MiB request-body limit](#streamable-http-request-bodies-are-limited-to-4-mib)) sit under MCPServer.

mkdocs.yml

@@ -67,6 +67,7 @@ nav:
       - Middleware: advanced/middleware.md
       - Extensions: advanced/extensions.md
       - MCP Apps: advanced/apps.md
+      - Startup cost: advanced/startup.md
   - Troubleshooting: troubleshooting.md
   - Migration Guide: migration.md
   - API Reference: api/

pyproject.toml

@@ -219,8 +219,10 @@ max-complexity = 24 # Default is 10
 "__init__.py" = ["F401"]
 # The mcp.types package is an alias that mirrors mcp_types namespaces by design.
 "src/mcp/types/*.py" = ["F403"]
-# Generated by scripts/gen_surface_types.py: raw datamodel-codegen output (TID251 lifts the repo-wide RootModel ban for these generated validators).
+# Generated by scripts/gen_surface_types.py: raw datamodel-codegen output (TID251 lifts the repo-wide RootModel ban for these generated validators
+# and their shared `WireRootModel` base).
 "src/mcp-types/mcp_types/_v*/__init__.py" = ["D212", "E501", "I001", "TID251", "UP007", "UP037"]
+"src/mcp-types/mcp_types/_wire_base.py" = ["TID251"]
 "tests/server/mcpserver/test_func_metadata.py" = ["E501"]
 "tests/shared/test_progress_notifications.py" = ["PLW0603"]
 

scripts/gen_surface_types.py

@@ -219,6 +219,28 @@ def patch(match: re.Match[str]) -> str:
     return source
 
 
+def use_deferred_bases(source: str) -> str:
+    """Route root models through the deferred `WireRootModel`; drop the trailing `model_rebuild()` calls.
+
+    Object models already defer via `--base-class WireModel`. A bare `RootModel[X]`
+    base parametrizes (and builds) eagerly, inline-generating the schema of every
+    deferred model the union references, so root models must defer too. The
+    trailing `X.model_rebuild()` block datamodel-codegen emits only force-built
+    forward references, which a deferred model resolves from the module namespace
+    on its first use.
+    """
+    source = source.replace("RootModel[", "WireRootModel[")
+    source = source.replace("import WireModel", "import WireModel, WireRootModel")
+    source = re.sub(r"^(from pydantic import .*), RootModel$", r"\1", source, flags=re.MULTILINE)
+    source = re.sub(r"^\w+\.model_rebuild\(\)\n", "", source, flags=re.MULTILINE)
+    # Drift guard: every root model routes through the deferred base and no rebuild call survives.
+    assert "WireRootModel[" in source and "RootModel[" not in source.replace("WireRootModel[", "")
+    assert ".model_rebuild()" not in source
+    # ...and no stray pydantic RootModel import survived (the strip above assumes it is trailing).
+    assert not re.search(r"^from pydantic import .*\bRootModel\b", source, flags=re.MULTILINE)
+    return source
+
+
 def build(entry: dict[str, str]) -> str:
     """Generate, post-process, and format one version's surface module text."""
     version = entry["protocol_version"]
@@ -243,12 +265,9 @@ def build(entry: dict[str, str]) -> str:
     # strict mkdocs link validation.
     source = source.replace("](/", "](https://modelcontextprotocol.io/")
     source = allow_open_class_extras(source, OPEN_CLASSES[version])
+    source = use_deferred_bases(source)
     if epilogue := EPILOGUES.get(version, ""):
-        # Insert before the trailing model_rebuild() block: pyright's evaluation
-        # order for the recursive RootModel block is sensitive to placement.
-        match = re.search(r"^\w+\.model_rebuild\(\)$", source, flags=re.MULTILINE)
-        cut = match.start() if match else len(source)
-        source = f"{source[:cut]}{epilogue}\n\n{source[cut:]}"
+        source = f"{source.rstrip()}\n\n\n{epilogue}"
     source = HEADER.format(version=version, sha=entry["sha256"]) + source
 
     staging = TYPES_DIR / f"_staging_{version}.py"