Document the import-cost contract and the deferred-work model

- 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.

Author: maxisbey

AGENTS.md

@@ -43,9 +43,41 @@
 - `src/mcp/__init__.py` defines the public API surface via `__all__`. Adding a
   symbol there is a deliberate API decision, not a convenience re-export.
 - IMPORTANT: All imports go at the top of the file — inline imports hide
-  dependencies and obscure circular-import bugs. Only exception: when a
+  dependencies and obscure circular-import bugs. Exceptions: 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), and the import-cost cases below.
+
+### Import cost
+
+Startup time is part of the API: `import mcp` is a lazy namespace and each
+entry point only loads what it uses. `tests/test_import_guards.py` pins
+which heavy dependencies each import path may load; a hoisted import that
+breaks one of these fails that test, so keep them off the paths below. Each
+such function-level or lazy import carries a one-line comment saying which
+stack it keeps out of which import path.
+
+- `mcp/__init__.py` and the `mcp.client` / `mcp.server` / `mcp.shared` /
+  `mcp.os` package inits resolve their exports and submodules on first
+  access (PEP 562 `__getattr__`); a bare `import mcp` loads no pydantic,
+  `mcp_types` or SDK submodule.
+- Client code never imports `mcp.server.*`: the in-process transport pieces
+  are imported inside the connector that only a live in-process `Server`
+  triggers, and `Server`/`MCPServer` are `TYPE_CHECKING`-only names.
+- `httpx2` loads only for the HTTP client transports (`streamable_http`,
+  `sse`), on the first URL `Client`; a stdio client never imports it.
+- The web stack (`starlette`, `sse_starlette`, `uvicorn`) loads only when an
+  HTTP app is built (`streamable_http_app()`, `sse_app()`, `custom_route()`),
+  never from `mcp.server`, the lowlevel `Server`, `MCPServer` or stdio; the
+  request access-token contextvar lives in the starlette-free
+  `mcp.server.auth.access_token` for that reason.
+- `opentelemetry` is imported on the first span, `cryptography`-backed
+  request-state codecs on first construction, `jwt`/`cryptography` only by
+  the auth paths that use them.
+- The per-version wire packages (`mcp_types._v2025_11_25`, `_v2026_07_28`)
+  load on the first message parsed for that protocol version, via the
+  `mcp_types.methods` surface maps - not on `import mcp_types`.
+- Pydantic models set `defer_build=True` (through `MCPModel`, the generated
+  wire bases, or per class): validators build on first use, not at import.
 
 ## Testing
 

docs/advanced/import-cost.md

@@ -0,0 +1,41 @@
+# Imports & startup time
+
+`import mcp` is close to free, and every entry point loads only what it uses. You get that
+without doing anything; this page is for when you want to know *what* loads *when*, or when you
+want to move the deferred work to a moment of your choosing.
+
+## What loads when
+
+The `mcp` package is a lazy namespace: `import mcp` binds no protocol types, no pydantic, and
+none of the client or server modules. Each name resolves from its home module the first time you
+touch it (`from mcp import Client` imports the client, `mcp.Tool` imports the types), and is then
+an ordinary attribute. `from mcp import *`, `dir(mcp)` and object identity are unchanged; the
+supported way to reach a submodule is still to import it (`import mcp.client.stdio`).
+
+From there, each stack loads with the feature that needs it:
+
+| Loaded on first use of | What loads |
+| --- | --- |
+| a URL `Client(...)` (or the SSE / streamable-HTTP client modules) | the HTTP client stack (`httpx2`) |
+| `streamable_http_app()` / `sse_app()` / `custom_route()` | the web stack (`starlette`, `sse_starlette`, `uvicorn`) |
+| the first message parsed for a protocol version | that version's wire-schema package (`mcp_types._v2025_11_25` / `_v2026_07_28`) |
+| the first construction or validation of a model | that model's pydantic validator (`defer_build=True`) |
+| the first span | the OpenTelemetry API |
+
+None of these is per request. Each is a one-time cost paid where the work happens, and the
+steady state afterwards is identical to having loaded it up front. Client code never loads the
+server stack, and a stdio server never loads the web stack.
+
+## Prewarming
+
+If you would rather pay the deferred work at startup than on the first request — a
+latency-sensitive host, say — trigger it explicitly before you start serving:
+
+```python
+--8<-- "docs_src/import_cost/tutorial001.py"
+```
+
+Reading a row of a surface map imports that protocol version's wire package, and
+`model_rebuild()` builds a model's validator; both are no-ops on anything already built. An HTTP
+server needs nothing extra for its transport: building the app (`streamable_http_app()`) at startup
+is exactly the moment its web stack loads anyway.

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.
+* **[Imports & startup time](import-cost.md)**: what the SDK loads when, and how to
+  move its deferred first-use work to startup if you want it there.
 
 A few things you might reasonably look for here live where you'd actually use them
 instead:

docs/migration.md

@@ -40,6 +40,7 @@ Every section heading below names the API it affects, so searching this page for
 | use stdio or streamable HTTP directly, or maintain a custom transport | [Transports](#transports) |
 | maintain OAuth client auth or a protected server | [OAuth and server auth](#oauth-and-server-auth) |
 | relied on lenient handling of off-schema traffic, or assert on exact wire bytes | [Stricter protocol validation and wire behavior](#stricter-protocol-validation-and-wire-behavior) |
+| rely on `import mcp` importing submodules, patch SDK internals, or subclass SDK pydantic models | [Import graph and startup](#import-graph-and-startup) |
 | test against in-memory server/client pairs | [Testing utilities](#testing-utilities) |
 | use roots, sampling, logging, or client-to-server progress | [Deprecations](#deprecations) |
 | operate servers that 2026-era clients will also connect to | [Notes for 2026-era connections](#notes-for-2026-era-connections) |
@@ -2678,6 +2679,57 @@ The envelope exists for OpenTelemetry trace propagation ([SEP-414](https://githu
 
 The SDK's new `opentelemetry-api` runtime dependency is covered under [Packaging, dependencies, and CLI](#packaging-dependencies-and-cli).
 
+## Import graph and startup
+
+### Imports are lazy; explicit imports are the supported form
+
+`import mcp` no longer imports the SDK's whole module graph: the `mcp` package resolves each
+export from its home module on first access, and every entry point loads only its own stack
+(no server code behind a client, no web framework behind a stdio server, no wire schemas
+before a message needs them). Nothing you import changes name or location, and
+`from mcp import Client`, `mcp.types.Tool`, `from mcp import *` and object identity behave as
+before. See [Imports & startup time](advanced/import-cost.md) for what loads when and how to
+prewarm it.
+
+Two incidental things did change:
+
+* **Attribute chains that were never imported explicitly.** `import mcp` used to bind most
+  submodules as a side effect, so `import mcp` followed by `mcp.client.stdio.stdio_client(...)`
+  happened to work. It still resolves (the packages import a submodule on attribute access), but
+  the supported form is to import what you use: `from mcp.client.stdio import stdio_client`, or
+  `import mcp.client.stdio`.
+* **Namespace bindings that tests used to patch.** Modules stopped re-binding names they only
+  imported: patch or import each object where it is defined. In particular,
+  `mcp.client.client.streamable_http_client` is `mcp.client.streamable_http.streamable_http_client`,
+  the HTTP-app pieces formerly bound in `mcp.server.lowlevel.server` / `mcp.server.mcpserver.server`
+  (`SseServerTransport`, `StreamableHTTPSessionManager`, the auth middleware and route builders)
+  live in `mcp.server.sse`, `mcp.server.streamable_http_manager` and `mcp.server.auth.*`, and
+  `get_access_token` / `auth_context_var` are defined in the transport-agnostic
+  `mcp.server.auth.access_token` (still importable from `mcp.server.auth.middleware.auth_context`).
+* **Two web-framework-free homes.** The resumability contract (`EventStore`, `EventMessage`,
+  `EventCallback`, `EventId`, `StreamId`) is defined in `mcp.server.event_store`, and
+  `TransportSecurityMiddleware` now lives beside the transports rather than in
+  `mcp.server.transport_security`; both keep their previous import paths
+  (`mcp.server.streamable_http.EventStore`, `mcp.server.transport_security.TransportSecurityMiddleware`,
+  same objects). Only code introspecting `Class.__module__` or pickling those *class objects* by
+  reference notices.
+* **Introspecting the app-builder signatures.** `typing.get_type_hints()` on the HTTP app
+  builders (`MCPServer.sse_app`, `MCPServer.streamable_http_app`, `Server.streamable_http_app`,
+  `MCPServer.custom_route`'s handler type) raises `NameError` for the Starlette-owned annotations
+  (`Starlette`, `Route`, `Request`, `Response`), which are typing-only now; every SDK-owned name in
+  those signatures still evaluates, and `inspect.signature()` is unaffected. Import starlette's
+  names into your own namespace and pass `localns=` if you need those hints evaluated.
+
+### Pydantic models build on first use (`defer_build=True`)
+
+The SDK's models and `TypeAdapter`s defer their validator build to first construction or
+validation instead of building at import; `inspect.signature(Model)`, `model_fields` and
+`model_json_schema()` report what they always did. A model you subclass from the SDK
+(`Tool`, `Resource`, `AuthSettings`, ...) inherits the deferral, so an annotation that cannot
+resolve in your subclass now surfaces at first use rather than at class creation. Set
+`model_config = ConfigDict(defer_build=False)` in your subclass, or call `Model.model_rebuild()`
+after defining it, if you want the build (and its errors) up front.
+
 ## Testing utilities
 
 ### `create_connected_server_and_client_session` removed

docs/whats-new.md

@@ -124,6 +124,10 @@ On those types, every Python attribute is now snake_case: `result.is_error`, `to
 
 **[Running your server](run/index.md)** covers the options; **[Add to an existing app](run/asgi.md)** covers mounting.
 
+### Imports pay for what you use
+
+`import mcp` is now nearly free, and every entry point loads only its own stack: a stdio server never loads the web framework, client code never loads the server, and the protocol's wire schemas load per negotiated version. The work did not vanish, it moved to first use (the first URL `Client`, the first HTTP app, the first message per protocol version), each a one-time cost. **[Imports & startup time](advanced/import-cost.md)** lists what loads when, and how to prewarm all of it at startup if that is where you want it.
+
 ### Behavior that changes without an import error
 
 The renames announce themselves. These do not:

docs_src/import_cost/__init__.py

@@ -0,0 +1,18 @@
+"""Prewarm the SDK's deferred startup work.
+
+Imports stay fast because the heavy pieces load on first use: a protocol
+version's wire schemas load on the first message parsed for that version, and
+each pydantic model builds its validator the first time it is used. A host that
+would rather pay all of that once, before serving traffic, can trigger it here.
+"""
+
+import mcp_types
+from mcp_types.methods import CLIENT_REQUESTS
+
+# Load the wire-schema package for each protocol version you will speak.
+# Reading any row of a surface map imports that version's package.
+_ = CLIENT_REQUESTS[("initialize", "2025-11-25")]
+
+# Build the validators for the models on your hot path up front.
+for model in (mcp_types.CallToolRequest, mcp_types.CallToolResult, mcp_types.Tool):
+    model.model_rebuild()

docs_src/import_cost/tutorial001.py

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

mkdocs.yml

@@ -0,0 +1,42 @@
+"""`docs/advanced/import-cost.md`: the prewarm recipe does what the page says."""
+
+import json
+import os
+import subprocess
+import sys
+
+# The recipe's effect is only observable in a fresh interpreter: this process has long
+# since loaded the wire packages and built the models.
+PROBE = """
+import json, sys
+import mcp_types
+
+before = {
+    "wire_2025_loaded": "mcp_types._v2025_11_25" in sys.modules,
+    "tool_built": mcp_types.Tool.__pydantic_complete__,
+}
+import docs_src.import_cost.tutorial001  # the recipe under test
+after = {
+    "wire_2025_loaded": "mcp_types._v2025_11_25" in sys.modules,
+    "tool_built": mcp_types.Tool.__pydantic_complete__,
+}
+print(json.dumps({"before": before, "after": after}))
+"""
+
+
+def test_prewarm_recipe_loads_the_wire_package_and_builds_the_models() -> None:
+    """tutorial001: before the recipe nothing is loaded/built; after it, the negotiated
+    version's wire package is imported and the named models are built."""
+    result = subprocess.run(
+        [sys.executable, "-c", PROBE],
+        capture_output=True,
+        text=True,
+        check=False,
+        timeout=60,
+        # pydantic plugins (e.g. logfire) building models is the environment's cost, not ours
+        env={**os.environ, "PYDANTIC_DISABLE_PLUGINS": "__all__"},
+    )
+    assert result.returncode == 0, result.stderr
+    observed = json.loads(result.stdout)
+    assert observed["before"] == {"wire_2025_loaded": False, "tool_built": False}
+    assert observed["after"] == {"wire_2025_loaded": True, "tool_built": True}