Wire per-version validation into ClientSession; fix elicit schema generation

ClientSession now uses parse_server_request/notification for inbound
dispatch (KeyError -> METHOD_NOT_FOUND), validates callback results
against the surface schema before sending (ValidationError ->
INTERNAL_ERROR), and gates server results through validate_server_result
before parsing. Adds a protocol_version property.

Surface codegen: SCHEMA_PATCHES targets ["integer", "number"] instead
of bare "number" so generated types use int | float (pydantic
smart-union preserves int through the sieve; previously coerced 37 ->
37.0). Regenerated both packages.

elicitation.py: Optional[T] fields now emit {"type": ...} with the
field omitted from required (was non-spec anyOf). Gate tightened to
reject list[...] and multi-primitive unions; only T or T | None
accepted. The interaction-suite divergence for nested requestedSchema is
flipped (client now rejects with INVALID_PARAMS).

Documented the elicit gate change in migration.md.

Author: maxisbey

docs/migration.md

@@ -535,6 +535,10 @@ await ctx.log(level="info", data="hello")
 
 Positional calls (`await ctx.info("hello")`) are unaffected.
 
+### `Context.elicit()` schema gate tightened
+
+`Context.elicit()` (and `elicit_with_validation()`) now accept only schemas whose fields are a single primitive type (`str`, `int`, `float`, `bool`) or `Optional[primitive]`. `list[...]` fields and unions of multiple primitives (e.g. `int | str`) raise `TypeError` at the call site; previously `list[str]` and arbitrary primitive unions were allowed but produced a `requestedSchema` outside the spec's restricted subset. `Optional[T]` fields now render as `{"type": ...}` with the field omitted from `required` instead of the non-spec `anyOf` shape.
+
 ### Replace `RootModel` by union types with `TypeAdapter` validation
 
 The following union types are no longer `RootModel` subclasses:

scripts/gen_surface_types.py

@@ -27,25 +27,30 @@
 
 # schema.ts -> schema.json renders TypeScript ``number`` as JSON Schema
 # ``integer`` at these sites; patch the JSON before codegen so floats validate.
+# Patched to ``["integer", "number"]`` (not bare ``"number"``) so codegen emits
+# ``int | float`` and pydantic's smart-union preserves ints on round-trip.
 # TODO: drop once modelcontextprotocol/modelcontextprotocol fixes the schema.ts -> schema.json number rendering.
 SCHEMA_PATCHES: dict[str, list[tuple[str, Any, Any]]] = {
     "2025-11-25": [
-        ("$defs/NumberSchema/properties/default/type", "integer", "number"),
-        ("$defs/NumberSchema/properties/maximum/type", "integer", "number"),
-        ("$defs/NumberSchema/properties/minimum/type", "integer", "number"),
+        ("$defs/NumberSchema/properties/default/type", "integer", ["integer", "number"]),
+        ("$defs/NumberSchema/properties/maximum/type", "integer", ["integer", "number"]),
+        ("$defs/NumberSchema/properties/minimum/type", "integer", ["integer", "number"]),
         (
             "$defs/ElicitResult/properties/content/additionalProperties/anyOf/1/type",
             ["string", "integer", "boolean"],
-            ["string", "number", "boolean"],
+            ["string", "integer", "number", "boolean"],
         ),
     ],
     "2026-07-28": [
+        ("$defs/NumberSchema/properties/default/type", "number", ["integer", "number"]),
+        ("$defs/NumberSchema/properties/maximum/type", "number", ["integer", "number"]),
+        ("$defs/NumberSchema/properties/minimum/type", "number", ["integer", "number"]),
         (
             "$defs/ElicitResult/properties/content/additionalProperties/anyOf/1/type",
             ["string", "integer", "boolean"],
-            ["string", "number", "boolean"],
+            ["string", "integer", "number", "boolean"],
         ),
-        ("$defs/JSONValue/anyOf/2/type", ["string", "integer", "boolean"], ["string", "number", "boolean"]),
+        ("$defs/JSONValue/anyOf/2/type", ["string", "integer", "boolean"], ["string", "integer", "number", "boolean"]),
     ],
 }
 

src/mcp/client/session.py

@@ -4,7 +4,7 @@
 from collections.abc import Mapping
 from dataclasses import dataclass
 from types import TracebackType
-from typing import Any, Protocol, cast, get_args
+from typing import Any, Protocol, cast
 
 import anyio
 import anyio.abc
@@ -22,7 +22,8 @@
 from mcp.shared.session import RequestResponder
 from mcp.shared.transport_context import TransportContext
 from mcp.shared.version import SUPPORTED_PROTOCOL_VERSIONS
-from mcp.types import RequestId, RequestParamsMeta
+from mcp.types import INTERNAL_ERROR, METHOD_NOT_FOUND, RequestId, RequestParamsMeta
+from mcp.types import methods as _methods
 
 DEFAULT_CLIENT_INFO = types.Implementation(name="mcp", version="0.1.0")
 
@@ -116,14 +117,6 @@ async def _default_logging_callback(
 
 ClientResponse: TypeAdapter[types.ClientResult | types.ErrorData] = TypeAdapter(types.ClientResult | types.ErrorData)
 
-_SERVER_REQUEST_METHODS: frozenset[str] = frozenset(
-    cast(type[BaseModel], arm).model_fields["method"].default for arm in get_args(types.ServerRequest)
-)
-"""Method names in the SDK's `ServerRequest` union, derived from the
-discriminator literal on each arm. Requests for any other method — including
-spec methods this SDK deliberately doesn't model, like `tasks/*` — are
-answered with METHOD_NOT_FOUND instead of failing union validation."""
-
 
 class ClientSession:
     """Client half of an MCP connection, running on a `Dispatcher`.
@@ -244,6 +237,12 @@ async def send_request(
             # The spec forbids cancelling initialize.
             opts["cancel_on_abandon"] = False
         raw = await self._dispatcher.send_raw_request(method, data.get("params"), opts)
+        # Literal fallback covers pre-handshake and stateless; matches runner.py.
+        version = self.protocol_version or "2025-11-25"
+        try:
+            _methods.validate_server_result(method, version, raw)
+        except KeyError:
+            pass
         return result_type.model_validate(raw, by_name=False)
 
     async def send_notification(self, notification: types.ClientNotification) -> None:
@@ -308,6 +307,11 @@ def initialize_result(self) -> types.InitializeResult | None:
         """
         return self._initialize_result
 
+    @property
+    def protocol_version(self) -> str | None:
+        """The negotiated protocol version. None until `initialize()` has completed."""
+        return self._initialize_result.protocol_version if self._initialize_result else None
+
     async def send_ping(self, *, meta: RequestParamsMeta | None = None) -> types.EmptyResult:
         """Send a ping request."""
         return await self.send_request(types.PingRequest(params=types.RequestParams(_meta=meta)), types.EmptyResult)
@@ -506,12 +510,14 @@ async def _on_request(
         self, dctx: DispatchContext[TransportContext], method: str, params: Mapping[str, Any] | None
     ) -> dict[str, Any]:
         """Answer a server-initiated request via the registered callbacks."""
-        if method not in _SERVER_REQUEST_METHODS:
-            raise MCPError(code=types.METHOD_NOT_FOUND, message="Method not found", data=method)
-        payload: dict[str, Any] = {"method": method}
-        if params is not None:
-            payload["params"] = dict(params)
-        request = types.server_request_adapter.validate_python(payload, by_name=False)
+        # Literal, not LATEST_PROTOCOL_VERSION: the fallback covers the initialize
+        # handshake (which only exists at <=2025) and stateless until the header
+        # is plumbed; its meaning is fixed regardless of LATEST bumps.
+        version = self.protocol_version or "2025-11-25"
+        try:
+            request = cast(types.ServerRequest, _methods.parse_server_request(method, version, params))
+        except KeyError:
+            raise MCPError(code=METHOD_NOT_FOUND, message="Method not found", data=method) from None
 
         response: types.ClientResult | types.ErrorData
         if isinstance(request, types.PingRequest):
@@ -532,19 +538,24 @@ async def _on_request(
         client_response = ClientResponse.validate_python(response)
         if isinstance(client_response, types.ErrorData):
             raise MCPError.from_error_data(client_response)
-        return client_response.model_dump(by_alias=True, mode="json", exclude_none=True)
+        dumped = client_response.model_dump(by_alias=True, mode="json", exclude_none=True)
+        try:
+            _methods.validate_client_result(method, version, dumped)
+        except ValidationError:
+            logger.exception("client callback for %r returned an invalid result", method)
+            raise MCPError(code=INTERNAL_ERROR, message="Client callback returned an invalid result") from None
+        return dumped
 
     async def _on_notify(
         self, dctx: DispatchContext[TransportContext], method: str, params: Mapping[str, Any] | None
     ) -> None:
         """Route a server notification: validate, run the typed callback, tee to message_handler."""
-        payload: dict[str, Any] = {"method": method}
-        if params is not None:
-            payload["params"] = dict(params)
+        # Same fallback as `_on_request`: covers pre-handshake and stateless.
+        version = self.protocol_version or "2025-11-25"
         try:
-            notification = types.server_notification_adapter.validate_python(payload, by_name=False)
-        except ValidationError:
-            logger.warning("Failed to validate notification: %s", payload, exc_info=True)
+            notification = cast(types.ServerNotification, _methods.parse_server_notification(method, version, params))
+        except (KeyError, ValidationError):
+            logger.warning("Failed to validate notification: %s", method, exc_info=True)
             return
         if isinstance(notification, types.CancelledNotification):
             # The dispatcher already applied the cancellation; not surfaced to message_handler.

src/mcp/server/elicitation.py

@@ -3,10 +3,11 @@
 from __future__ import annotations
 
 import types
-from collections.abc import Sequence
-from typing import Generic, Literal, TypeVar, Union, get_args, get_origin
+from typing import Any, Generic, Literal, TypeVar, Union, get_args, get_origin
 
 from pydantic import BaseModel
+from pydantic.json_schema import GenerateJsonSchema, JsonSchemaValue
+from pydantic_core import core_schema
 
 from mcp.server.session import ServerSession
 from mcp.types import RequestId
@@ -49,56 +50,43 @@ class AcceptedUrlElicitation(BaseModel):
 _ELICITATION_PRIMITIVE_TYPES = (str, int, float, bool)
 
 
+class _ElicitationJsonSchema(GenerateJsonSchema):
+    """JSON-Schema generator that flattens `T | None` to `T` and drops `None` defaults.
+
+    The spec's `PrimitiveSchemaDefinition` admits no `anyOf` or null type; an
+    optional field is expressed by leaving it out of `required`, which pydantic
+    already does for any field with a default.
+    """
+
+    def nullable_schema(self, schema: core_schema.NullableSchema) -> JsonSchemaValue:
+        return self.generate_inner(schema["schema"])
+
+    def default_schema(self, schema: core_schema.WithDefaultSchema) -> JsonSchemaValue:
+        result = super().default_schema(schema)
+        if result.get("default") is None:
+            result.pop("default", None)
+        return result
+
+
 def _validate_elicitation_schema(schema: type[BaseModel]) -> None:
     """Validate that a Pydantic model only contains primitive field types."""
     for field_name, field_info in schema.model_fields.items():
-        annotation = field_info.annotation
-
-        if annotation is None or annotation is types.NoneType:  # pragma: no cover
-            continue
-        elif _is_primitive_field(annotation):
-            continue
-        elif _is_string_sequence(annotation):
-            continue
-        else:
+        if not _is_primitive_field(field_info.annotation):
             raise TypeError(
                 f"Elicitation schema field '{field_name}' must be a primitive type "
-                f"{_ELICITATION_PRIMITIVE_TYPES}, a sequence of strings (list[str], etc.), "
-                f"or Optional of these types. Nested models and complex types are not allowed."
+                f"{_ELICITATION_PRIMITIVE_TYPES} or Optional of one. Unions of multiple "
+                f"primitives, lists, and nested models are not allowed."
             )
 
 
-def _is_string_sequence(annotation: type) -> bool:
-    """Check if annotation is a sequence of strings (list[str], Sequence[str], etc)."""
-    origin = get_origin(annotation)
-    # Check if it's a sequence-like type with str elements
-    if origin:
-        try:
-            if issubclass(origin, Sequence):
-                args = get_args(annotation)
-                # Should have single str type arg
-                return len(args) == 1 and args[0] is str
-        except TypeError:  # pragma: no cover
-            # origin is not a class, so it can't be a subclass of Sequence
-            pass
-    return False
-
-
-def _is_primitive_field(annotation: type) -> bool:
-    """Check if a field is a primitive type allowed in elicitation schemas."""
-    # Handle basic primitive types
+def _is_primitive_field(annotation: Any) -> bool:
+    """True if `annotation` is a single primitive type, optionally wrapped in `Optional`."""
     if annotation in _ELICITATION_PRIMITIVE_TYPES:
         return True
-
-    # Handle Union types
     origin = get_origin(annotation)
     if origin is Union or origin is types.UnionType:
-        args = get_args(annotation)
-        # All args must be primitive types, None, or string sequences
-        return all(
-            arg is types.NoneType or arg in _ELICITATION_PRIMITIVE_TYPES or _is_string_sequence(arg) for arg in args
-        )
-
+        non_none = [a for a in get_args(annotation) if a is not types.NoneType]
+        return len(non_none) == 1 and non_none[0] in _ELICITATION_PRIMITIVE_TYPES
     return False
 
 
@@ -121,7 +109,7 @@ async def elicit_with_validation(
     # Validate that schema only contains primitive types and fail loudly if not
     _validate_elicitation_schema(schema)
 
-    json_schema = schema.model_json_schema()
+    json_schema = schema.model_json_schema(schema_generator=_ElicitationJsonSchema)
 
     result = await session.elicit_form(
         message=message,

src/mcp/types/v2025_11_25/__init__.py

@@ -311,7 +311,7 @@ class ElicitResult(WireModel):
     - "decline": User explicitly decline the action
     - "cancel": User dismissed without making an explicit choice
     """
-    content: dict[str, list[str] | str | float | bool] | None = None
+    content: dict[str, list[str] | str | int | float | bool] | None = None
     """
     The submitted form data, only present when action is "accept" and mode was "form".
     Contains values matching the requested schema.
@@ -685,10 +685,10 @@ class NumberSchema(WireModel):
     model_config = ConfigDict(
         extra="ignore",
     )
-    default: float | None = None
+    default: int | float | None = None
     description: str | None = None
-    maximum: float | None = None
-    minimum: float | None = None
+    maximum: int | float | None = None
+    minimum: int | float | None = None
     title: str | None = None
     type: Literal["integer", "number"]
 

src/mcp/types/v2026_07_28/__init__.py

@@ -144,7 +144,7 @@ class ElicitResult(WireModel):
     - `"decline"`: User explicitly declined the action
     - `"cancel"`: User dismissed without making an explicit choice
     """
-    content: dict[str, list[str] | str | float | bool] | None = None
+    content: dict[str, list[str] | str | int | float | bool] | None = None
     """
     The submitted form data, only present when action is `"accept"` and mode was `"form"`.
     Contains values matching the requested schema.
@@ -585,10 +585,10 @@ class NumberSchema(WireModel):
     model_config = ConfigDict(
         extra="ignore",
     )
-    default: float | None = None
+    default: int | float | None = None
     description: str | None = None
-    maximum: float | None = None
-    minimum: float | None = None
+    maximum: int | float | None = None
+    minimum: int | float | None = None
     title: str | None = None
     type: Literal["integer", "number"]
 
@@ -3536,8 +3536,8 @@ class JSONObject(RootModel[dict[str, "JSONValue"]]):
     root: dict[str, "JSONValue"]
 
 
-class JSONValue(RootModel[Union[JSONObject, list["JSONValue"], str | float | bool]]):
-    root: Union[JSONObject, list["JSONValue"], str | float | bool]
+class JSONValue(RootModel[Union[JSONObject, list["JSONValue"], str | int | float | bool]]):
+    root: Union[JSONObject, list["JSONValue"], str | int | float | bool]
 
 
 AnyCallToolResult = CallToolResult | InputRequiredResult