Defer building the SDK's own eager pydantic models and adapters

Every SDK-defined model that used to be built at import - the auth and
OAuth handler models, mcpserver's Resource/ResourceTemplate/Prompt/Tool/
Settings/Context/FuncMetadata, the client's parameter models, transport
security, apps and elicitation results - now sets defer_build=True, and
the remaining module-level TypeAdapters (message_validator,
token_request_adapter) build on first use as well. Each model or validator
is built once, at its first construction or validation, instead of adding
its cost to the import of the module that defines it.

Models that derive from BaseModel directly opt into the lazy __signature__
with @deferred_model, so inspect.signature() on a never-used model keeps
reporting its fields (and mcpserver Settings, whose signature could not
resolve at all before, now does).

Author: maxisbey

src/mcp/client/auth/extensions/client_credentials.py

@@ -13,7 +13,8 @@
 
 import httpx2
 import jwt
-from pydantic import BaseModel, Field
+from mcp_types._deferred import deferred_model
+from pydantic import BaseModel, ConfigDict, Field
 
 from mcp.client.auth import OAuthClientProvider, OAuthFlowError, TokenStorage
 from mcp.shared.auth import OAuthClientInformationFull, OAuthClientMetadata
@@ -134,6 +135,7 @@ async def provider(audience: str) -> str:
     return provider
 
 
+@deferred_model
 class SignedJWTParameters(BaseModel):
     """Parameters for creating SDK-signed JWT assertions.
 
@@ -156,6 +158,9 @@ class SignedJWTParameters(BaseModel):
         ```
     """
 
+    # defer_build: build the validator on first use rather than at import (import-time cost).
+    model_config = ConfigDict(defer_build=True)
+
     issuer: str = Field(description="Issuer for JWT assertions (typically client_id).")
     subject: str = Field(description="Subject identifier for JWT assertions (typically client_id).")
     signing_key: str = Field(description="Private key for JWT signing (PEM format).")

src/mcp/client/auth/oauth2.py

@@ -16,8 +16,9 @@
 
 import anyio
 import httpx2
+from mcp_types._deferred import deferred_model
 from mcp_types.version import is_version_at_least
-from pydantic import BaseModel, Field, ValidationError
+from pydantic import BaseModel, ConfigDict, Field, ValidationError
 
 from mcp.client.auth.exceptions import OAuthFlowError, OAuthRegistrationError, OAuthTokenError
 from mcp.client.auth.utils import (
@@ -109,9 +110,13 @@ def check_registration_usable(client_info: OAuthClientInformationFull) -> None:
         )
 
 
+@deferred_model
 class PKCEParameters(BaseModel):
     """PKCE (Proof Key for Code Exchange) parameters."""
 
+    # defer_build: build the validator on first use rather than at import (import-time cost).
+    model_config = ConfigDict(defer_build=True)
+
     code_verifier: str = Field(..., min_length=43, max_length=128)
     code_challenge: str = Field(..., min_length=43, max_length=128)
 

src/mcp/client/session_group.py

@@ -16,7 +16,8 @@
 import anyio
 import httpx2
 import mcp_types as types
-from pydantic import BaseModel, Field
+from mcp_types._deferred import deferred_model
+from pydantic import BaseModel, ConfigDict, Field
 from typing_extensions import Self
 
 import mcp
@@ -28,10 +29,16 @@
 from mcp.shared.dispatcher import ProgressFnT
 from mcp.shared.exceptions import MCPError
 
+# `defer_build=True` below: pydantic builds each validator on first use rather than at
+# import (import-time cost); the build is transparent at first construction/validation.
 
+
+@deferred_model
 class SseServerParameters(BaseModel):
     """Parameters for initializing an sse_client."""
 
+    model_config = ConfigDict(defer_build=True)
+
     # The endpoint URL.
     url: str
 
@@ -45,9 +52,12 @@ class SseServerParameters(BaseModel):
     sse_read_timeout: float = 300.0
 
 
+@deferred_model
 class StreamableHttpParameters(BaseModel):
     """Parameters for initializing a streamable_http_client."""
 
+    model_config = ConfigDict(defer_build=True)
+
     # The endpoint URL.
     url: str
 
@@ -104,6 +114,8 @@ class ClientSessionGroup:
     class _ComponentNames(BaseModel):
         """Used for reverse index to find components."""
 
+        model_config = ConfigDict(defer_build=True)
+
         prompts: set[str] = Field(default_factory=set)
         resources: set[str] = Field(default_factory=set)
         tools: set[str] = Field(default_factory=set)

src/mcp/client/stdio.py

@@ -21,7 +21,8 @@
 import mcp_types as types
 from anyio.abc import AsyncResource, Process
 from anyio.streams.text import TextReceiveStream
-from pydantic import BaseModel, Field
+from mcp_types._deferred import deferred_model
+from pydantic import BaseModel, ConfigDict, Field
 
 from mcp.client._transport import TransportStreams
 from mcp.os.posix.utilities import terminate_posix_process_tree
@@ -90,7 +91,11 @@ def get_default_environment() -> dict[str, str]:
     return env
 
 
+@deferred_model
 class StdioServerParameters(BaseModel):
+    # defer_build: build the validator on first use rather than at import (import-time cost).
+    model_config = ConfigDict(defer_build=True)
+
     command: str
     """The executable to run to start the server."""
 

src/mcp/server/apps.py

@@ -32,6 +32,7 @@ def get_time(ctx: Context) -> str:
 from collections.abc import Callable, Sequence
 from typing import Any, Literal, TypeVar
 
+from mcp_types._deferred import deferred_model
 from pydantic import BaseModel, ConfigDict
 from pydantic.alias_generators import to_camel
 
@@ -52,21 +53,24 @@ def get_time(ctx: Context) -> str:
 _CallableT = TypeVar("_CallableT", bound=Callable[..., Any])
 
 
+@deferred_model
 class ResourcePermissions(BaseModel):
     """Iframe permissions a `ui://` resource requests (`_meta.ui.permissions`)."""
 
-    model_config = ConfigDict(alias_generator=to_camel, populate_by_name=True)
+    # defer_build: build the validator on first use rather than at import (import-time cost).
+    model_config = ConfigDict(alias_generator=to_camel, populate_by_name=True, defer_build=True)
 
     camera: dict[str, Any] | None = None
     microphone: dict[str, Any] | None = None
     geolocation: dict[str, Any] | None = None
     clipboard_write: dict[str, Any] | None = None
 
 
+@deferred_model
 class ResourceCsp(BaseModel):
     """Content-Security-Policy domains for a `ui://` resource (`_meta.ui.csp`)."""
 
-    model_config = ConfigDict(alias_generator=to_camel, populate_by_name=True)
+    model_config = ConfigDict(alias_generator=to_camel, populate_by_name=True, defer_build=True)
 
     connect_domains: list[str] | None = None
     resource_domains: list[str] | None = None

src/mcp/server/auth/handlers/authorize.py

@@ -3,7 +3,8 @@
 from typing import Any, Literal
 
 # TODO(Marcelo): We should drop the `RootModel`.
-from pydantic import AnyUrl, BaseModel, Field, RootModel, ValidationError  # noqa: TID251
+from mcp_types._deferred import deferred_model
+from pydantic import AnyUrl, BaseModel, ConfigDict, Field, RootModel, ValidationError  # noqa: TID251
 from starlette.datastructures import FormData, QueryParams
 from starlette.requests import Request
 from starlette.responses import RedirectResponse, Response
@@ -22,7 +23,14 @@
 logger = logging.getLogger(__name__)
 
 
+# `defer_build=True` below: pydantic builds each validator on first use rather than at
+# import (import-time cost); the build is transparent at first construction/validation.
+
+
+@deferred_model
 class AuthorizationRequest(BaseModel):
+    model_config = ConfigDict(defer_build=True)
+
     # See https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.1
     client_id: str = Field(..., description="The client ID")
     redirect_uri: AnyUrl | None = Field(None, description="URL to redirect to after authorization")
@@ -42,7 +50,10 @@ class AuthorizationRequest(BaseModel):
     )
 
 
+@deferred_model
 class AuthorizationErrorResponse(BaseModel):
+    model_config = ConfigDict(defer_build=True)
+
     error: AuthorizationErrorCode
     error_description: str | None
     error_uri: AnyUrl | None = None
@@ -59,7 +70,10 @@ def best_effort_extract_string(key: str, params: None | FormData | QueryParams)
     return None
 
 
+@deferred_model
 class AnyUrlModel(RootModel[AnyUrl]):
+    model_config = ConfigDict(defer_build=True)
+
     root: AnyUrl
 
 

src/mcp/server/auth/handlers/register.py

@@ -4,7 +4,8 @@
 from typing import Any
 from uuid import uuid4
 
-from pydantic import BaseModel, ValidationError
+from mcp_types._deferred import deferred_model
+from pydantic import BaseModel, ConfigDict, ValidationError
 from starlette.requests import Request
 from starlette.responses import Response
 
@@ -19,7 +20,11 @@
 RegistrationRequest = OAuthClientMetadata
 
 
+@deferred_model
 class RegistrationErrorResponse(BaseModel):
+    # defer_build: build the validator on first use rather than at import (import-time cost).
+    model_config = ConfigDict(defer_build=True)
+
     error: RegistrationErrorCode
     error_description: str | None
 

src/mcp/server/auth/handlers/revoke.py

@@ -2,7 +2,8 @@
 from functools import partial
 from typing import Any, Literal
 
-from pydantic import BaseModel, ValidationError
+from mcp_types._deferred import deferred_model
+from pydantic import BaseModel, ConfigDict, ValidationError
 from starlette.requests import Request
 from starlette.responses import Response
 
@@ -13,17 +14,26 @@
 from mcp.server.auth.middleware.client_auth import AuthenticationError, ClientAuthenticator
 from mcp.server.auth.provider import AccessToken, OAuthAuthorizationServerProvider, RefreshToken
 
+# `defer_build=True` below: pydantic builds each validator on first use rather than at
+# import (import-time cost); the build is transparent at first construction/validation.
 
+
+@deferred_model
 class RevocationRequest(BaseModel):
     """See https://datatracker.ietf.org/doc/html/rfc7009#section-2.1"""
 
+    model_config = ConfigDict(defer_build=True)
+
     token: str
     token_type_hint: Literal["access_token", "refresh_token"] | None = None
     client_id: str
     client_secret: str | None
 
 
+@deferred_model
 class RevocationErrorResponse(BaseModel):
+    model_config = ConfigDict(defer_build=True)
+
     error: Literal["invalid_request", "unauthorized_client"]
     error_description: str | None = None
 

src/mcp/server/auth/handlers/token.py

@@ -4,7 +4,8 @@
 from dataclasses import dataclass
 from typing import Annotated, Any, Literal
 
-from pydantic import AnyHttpUrl, AnyUrl, BaseModel, Field, TypeAdapter, ValidationError
+from mcp_types._deferred import deferred_model
+from pydantic import AnyHttpUrl, AnyUrl, BaseModel, ConfigDict, Field, TypeAdapter, ValidationError
 from starlette.requests import Request
 
 from mcp.server.auth.errors import stringify_pydantic_error
@@ -18,8 +19,14 @@
 )
 from mcp.shared.auth import OAuthToken
 
+# `defer_build=True` below: pydantic builds each validator on first use rather than at
+# import (import-time cost); the build is transparent at first construction/validation.
 
+
+@deferred_model
 class AuthorizationCodeRequest(BaseModel):
+    model_config = ConfigDict(defer_build=True)
+
     # See https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.3
     grant_type: Literal["authorization_code"]
     code: str = Field(..., description="The authorization code")
@@ -33,7 +40,10 @@ class AuthorizationCodeRequest(BaseModel):
     resource: str | None = Field(None, description="Resource indicator for the token")
 
 
+@deferred_model
 class RefreshTokenRequest(BaseModel):
+    model_config = ConfigDict(defer_build=True)
+
     # See https://datatracker.ietf.org/doc/html/rfc6749#section-6
     grant_type: Literal["refresh_token"]
     refresh_token: str = Field(..., description="The refresh token")
@@ -45,7 +55,10 @@ class RefreshTokenRequest(BaseModel):
     resource: str | None = Field(None, description="Resource indicator for the token")
 
 
+@deferred_model
 class JwtBearerRequest(BaseModel):
+    model_config = ConfigDict(defer_build=True)
+
     # RFC 7523 §2.1 JWT bearer authorization grant. SEP-990 leg 2: the client presents the
     # enterprise IdP-issued ID-JAG to the MCP authorization server as the `assertion`.
     grant_type: Literal["urn:ietf:params:oauth:grant-type:jwt-bearer"]
@@ -63,12 +76,15 @@ class JwtBearerRequest(BaseModel):
     AuthorizationCodeRequest | RefreshTokenRequest | JwtBearerRequest,
     Field(discriminator="grant_type"),
 ]
-token_request_adapter = TypeAdapter[TokenRequest](TokenRequest)
+token_request_adapter = TypeAdapter[TokenRequest](TokenRequest, config=ConfigDict(defer_build=True))
 
 
+@deferred_model
 class TokenErrorResponse(BaseModel):
     """See https://datatracker.ietf.org/doc/html/rfc6749#section-5.2"""
 
+    model_config = ConfigDict(defer_build=True)
+
     error: TokenErrorCode
     error_description: str | None = None
     error_uri: AnyHttpUrl | None = None

src/mcp/server/auth/provider.py

@@ -2,12 +2,19 @@
 from typing import Any, Generic, Literal, Protocol, TypeVar
 from urllib.parse import parse_qs, urlencode, urlparse, urlunparse
 
-from pydantic import AnyUrl, BaseModel
+from mcp_types._deferred import deferred_model
+from pydantic import AnyUrl, BaseModel, ConfigDict
 
 from mcp.shared.auth import OAuthClientInformationFull, OAuthToken
 
+# `defer_build=True` on the models below: pydantic builds each validator on first use
+# rather than at import (import-time cost); the build is transparent at first construction.
 
+
+@deferred_model
 class AuthorizationParams(BaseModel):
+    model_config = ConfigDict(defer_build=True)
+
     state: str | None
     scopes: list[str] | None
     code_challenge: str
@@ -16,6 +23,7 @@ class AuthorizationParams(BaseModel):
     resource: str | None = None  # RFC 8707 resource indicator
 
 
+@deferred_model
 class IdentityAssertionParams(BaseModel):
     """Validated parameters of a SEP-990 identity-assertion (RFC 7523 jwt-bearer) request.
 
@@ -24,12 +32,17 @@ class IdentityAssertionParams(BaseModel):
     RFC 7523 §3 and the SEP-990 §5.1 processing rules before issuing an access token.
     """
 
+    model_config = ConfigDict(defer_build=True)
+
     assertion: str  # RFC 7523 §2.1: the JWT (ID-JAG) presented as the authorization grant
     scopes: list[str] | None = None
     resource: str | None = None  # RFC 8707 resource indicator from the token request
 
 
+@deferred_model
 class AuthorizationCode(BaseModel):
+    model_config = ConfigDict(defer_build=True)
+
     code: str
     scopes: list[str]
     expires_at: float
@@ -41,15 +54,21 @@ class AuthorizationCode(BaseModel):
     subject: str | None = None  # resource owner; propagate to the issued AccessToken
 
 
+@deferred_model
 class RefreshToken(BaseModel):
+    model_config = ConfigDict(defer_build=True)
+
     token: str
     client_id: str
     scopes: list[str]
     expires_at: int | None = None
     subject: str | None = None  # resource owner; propagate to refreshed AccessTokens
 
 
+@deferred_model
 class AccessToken(BaseModel):
+    model_config = ConfigDict(defer_build=True)
+
     token: str
     client_id: str
     scopes: list[str]