Wire per-version validation into ServerRunner

- Add validate_client_request/notification, validate_server_result to
  types.methods (surface-only siblings of the parse_* functions)
- ServerRunner validates inbound requests/notifications against the
  negotiated version's surface schema; custom methods fall through to
  the registered params_type as before
- Handler results are validated against the surface schema after dump;
  a spec-invalid result is logged and returns INTERNAL_ERROR to the client
- Map JSON-Schema format byte/uri/uri-template to plain str in codegen
  (Base64Str and AnyUrl over-assert on annotation-only formats);
  regenerate both surface packages
- Fix two test fixtures that built Tool(input_schema={}) without the
  spec-required type field
- Document handler-result validation in migration.md

Author: maxisbey

docs/migration.md

@@ -225,6 +225,10 @@ Because `populate_by_name=True` is set, the old camelCase names still work as co
 
 Serialized results now include `resultType` by default (and `ttlMs`/`cacheScope` on cacheable results). Peers ignore unknown result fields, so this interoperates across protocol versions, but tests or recorded fixtures that compare exact serialized payloads need the new keys added.
 
+### Server handler results are validated against the protocol schema
+
+Results returned from server handlers are now validated against the negotiated protocol version's schema before being sent. A result that does not conform raises on the server side and the client receives an `INTERNAL_ERROR` response. The case most existing code will hit is `Tool.inputSchema`: the spec requires it to contain `"type": "object"`, so an empty `{}` is now rejected.
+
 ### `args` parameter removed from `ClientSessionGroup.call_tool()`
 
 The deprecated `args` parameter has been removed from `ClientSessionGroup.call_tool()`. Use `arguments` instead.

scripts/gen_surface_types.py

@@ -110,6 +110,9 @@ def run_codegen(schema_path: Path, output_path: Path) -> None:
             "--enum-field-as-literal", "all",
             "--use-union-operator", "--use-double-quotes",
             "--extra-fields", "allow",
+            # JSON Schema `format` is annotation-only; codegen's defaults
+            # (Base64Str, AnyUrl) over-assert and reject valid wire data.
+            "--type-mappings", "byte=string", "uri=string", "uri-template=string",
             "--disable-timestamp",
         ],
         capture_output=True, text=True,

src/mcp/server/runner.py

@@ -19,7 +19,7 @@
 from collections.abc import Mapping
 from dataclasses import dataclass, field
 from functools import partial, reduce
-from typing import TYPE_CHECKING, Any, Generic, cast, get_args
+from typing import TYPE_CHECKING, Any, Generic, cast
 
 import anyio.abc
 from opentelemetry.trace import SpanKind, StatusCode
@@ -38,19 +38,18 @@
 from mcp.shared.transport_context import TransportContext
 from mcp.shared.version import SUPPORTED_PROTOCOL_VERSIONS
 from mcp.types import (
+    INTERNAL_ERROR,
     INVALID_PARAMS,
     LATEST_PROTOCOL_VERSION,
     METHOD_NOT_FOUND,
-    ClientRequest,
     ErrorData,
     Implementation,
     InitializeRequestParams,
     InitializeResult,
-    NotificationParams,
     RequestParams,
     RequestParamsMeta,
-    client_request_adapter,
 )
+from mcp.types import methods as _methods
 
 if TYPE_CHECKING:
     from mcp.server.lowlevel.server import Server
@@ -80,14 +79,6 @@ def _extract_meta(params: Mapping[str, Any] | None) -> RequestParamsMeta | None:
         return None
 
 
-_SPEC_CLIENT_METHODS: frozenset[str] = frozenset(
-    cast(type[BaseModel], arm).model_fields["method"].default for arm in get_args(ClientRequest)
-)
-"""Method names in the spec `ClientRequest` union, derived from the
-discriminator literal on each arm. Used to gate upfront validation so custom
-methods registered via `add_request_handler` are not rejected."""
-
-
 def otel_middleware(next_on_request: OnRequest) -> OnRequest:
     """Dispatch-tier middleware that wraps each request in an OpenTelemetry span.
 
@@ -228,16 +219,19 @@ async def _on_request(
         params: Mapping[str, Any] | None,
     ) -> dict[str, Any]:
         ctx = self._make_context(dctx, _extract_meta(params))
+        # Fallback covers the initialize handshake itself and stateless mode
+        # until the per-request version header is plumbed through.
+        version = self.connection.protocol_version or LATEST_PROTOCOL_VERSION
 
         async def _inner() -> HandlerResult:
-            # TODO(maxisbey): pinned compat: spec methods are validated against
-            # the ClientRequest union before lookup, so malformed params are
-            # INVALID_PARAMS even with no handler registered.
-            if method in _SPEC_CLIENT_METHODS:
-                payload: dict[str, Any] = {"method": method}
-                if params is not None:
-                    payload["params"] = dict(params)
-                client_request_adapter.validate_python(payload, by_name=False)
+            # Pinned compat: spec methods are surface-validated before lookup,
+            # so malformed params are INVALID_PARAMS even with no handler
+            # registered. Custom methods miss the surface map and fall through
+            # to `entry.params_type` exactly as before.
+            try:
+                _methods.validate_client_request(method, version, params)
+            except KeyError:
+                pass  # not a spec method at this version; lookup below handles it
             # TODO(maxisbey): the 2026-07-28 spec drops the handshake; this branch and
             # the gate become a per-version legacy path then. Initialize runs inline
             # (read loop parked), so awaiting the peer anywhere on this path deadlocks.
@@ -265,6 +259,15 @@ async def _inner() -> HandlerResult:
 
         call = self._compose_server_middleware(ctx, method, params, _inner)
         result = _dump_result(await call())
+        try:
+            _methods.validate_server_result(method, version, result)
+        except KeyError:
+            pass  # custom method; no result schema
+        except ValidationError:
+            # Server bug, not client fault. Detail stays in the server log:
+            # pydantic messages echo the result body.
+            logger.exception("handler for %r returned an invalid result", method)
+            raise MCPError(code=INTERNAL_ERROR, message="Handler returned an invalid result") from None
         if method == "initialize":
             # Commit only on chain success, so a middleware veto leaves no state.
             # Race-free: the read loop is parked until this call returns.
@@ -278,18 +281,21 @@ async def _on_notify(
         params: Mapping[str, Any] | None,
     ) -> None:
         ctx = self._make_context(dctx, _extract_meta(params))
+        # Same fallback as `_on_request`: covers pre-handshake and stateless.
+        version = self.connection.protocol_version or LATEST_PROTOCOL_VERSION
 
         async def _inner() -> None:
+            try:
+                _methods.validate_client_notification(method, version, params)
+            except KeyError:
+                pass  # not a spec notification at this version
+            except ValidationError:
+                logger.warning("dropped %r: malformed params", method)
+                return
             if method == "notifications/initialized":
-                # Validate before committing so a malformed notification leaves
-                # state untouched; then fall through so a registered handler
-                # observes an initialized connection.
-                if params is not None:
-                    try:
-                        NotificationParams.model_validate(params, by_name=False)
-                    except ValidationError:
-                        logger.warning("dropped %r: malformed params", method)
-                        return
+                # Surface validation above already rejected a malformed body, so
+                # commit; fall through so a registered handler observes an
+                # initialized connection.
                 self.connection.initialized.set()
             elif not self.connection.initialize_accepted:
                 logger.debug("dropped %s: received before initialization", method)

src/mcp/types/methods.py

@@ -34,6 +34,9 @@
     "parse_server_notification",
     "parse_server_request",
     "parse_server_result",
+    "validate_client_notification",
+    "validate_client_request",
+    "validate_server_result",
 ]
 
 
@@ -427,6 +430,24 @@ def _monolith_row(monolith: Mapping[str, _MonolithT], method: str) -> _MonolithT
         raise RuntimeError(f"inconsistent extension maps: surface defines {method!r} but monolith does not") from None
 
 
+def validate_client_request(
+    method: str,
+    version: str,
+    params: Mapping[str, Any] | None,
+    *,
+    surface: Mapping[tuple[str, str], type[BaseModel]] = CLIENT_REQUESTS,
+) -> None:
+    """Validate a client request against `surface` only.
+
+    Raises:
+        ValueError: `version` is not a known protocol version.
+        KeyError: `(method, version)` is not in `surface` (the version gate).
+        pydantic.ValidationError: body fails surface validation.
+    """
+    _check_known_version(version)
+    surface[(method, version)].model_validate({**_REQUEST_STUB, **_body(method, params)}, by_name=False)
+
+
 def parse_client_request(
     method: str,
     version: str,
@@ -450,9 +471,7 @@ def parse_client_request(
         pydantic.ValidationError: body fails surface or monolith validation.
         RuntimeError: surface matched but `method` has no monolith row.
     """
-    _check_known_version(version)
-    surface_type = surface[(method, version)]
-    surface_type.model_validate({**_REQUEST_STUB, **_body(method, params)}, by_name=False)
+    validate_client_request(method, version, params, surface=surface)
     return _monolith_row(monolith, method).model_validate(_body(method, params), by_name=False)
 
 
@@ -485,6 +504,24 @@ def parse_server_request(
     return _monolith_row(monolith, method).model_validate(_body(method, params), by_name=False)
 
 
+def validate_client_notification(
+    method: str,
+    version: str,
+    params: Mapping[str, Any] | None,
+    *,
+    surface: Mapping[tuple[str, str], type[BaseModel]] = CLIENT_NOTIFICATIONS,
+) -> None:
+    """Validate a client notification against `surface` only.
+
+    Raises:
+        ValueError: `version` is not a known protocol version.
+        KeyError: `(method, version)` is not in `surface`.
+        pydantic.ValidationError: body fails surface validation.
+    """
+    _check_known_version(version)
+    surface[(method, version)].model_validate({**_NOTIFICATION_STUB, **_body(method, params)}, by_name=False)
+
+
 def parse_client_notification(
     method: str,
     version: str,
@@ -508,9 +545,7 @@ def parse_client_notification(
         pydantic.ValidationError: body fails surface or monolith validation.
         RuntimeError: surface matched but `method` has no monolith row.
     """
-    _check_known_version(version)
-    surface_type = surface[(method, version)]
-    surface_type.model_validate({**_NOTIFICATION_STUB, **_body(method, params)}, by_name=False)
+    validate_client_notification(method, version, params, surface=surface)
     return _monolith_row(monolith, method).model_validate(_body(method, params), by_name=False)
 
 
@@ -543,6 +578,24 @@ def parse_server_notification(
     return _monolith_row(monolith, method).model_validate(_body(method, params), by_name=False)
 
 
+def validate_server_result(
+    method: str,
+    version: str,
+    data: Mapping[str, Any],
+    *,
+    surface: Mapping[tuple[str, str], type[BaseModel] | UnionType] = SERVER_RESULTS,
+) -> None:
+    """Validate a server result against `surface` only.
+
+    Raises:
+        ValueError: `version` is not a known protocol version.
+        KeyError: `(method, version)` is not in `surface`.
+        pydantic.ValidationError: result fails surface validation.
+    """
+    _check_known_version(version)
+    _adapter(surface[(method, version)]).validate_python(data, by_name=False)
+
+
 def parse_server_result(
     method: str,
     version: str,
@@ -566,8 +619,7 @@ def parse_server_result(
         pydantic.ValidationError: result fails surface or monolith validation.
         RuntimeError: surface matched but `method` has no monolith row.
     """
-    _check_known_version(version)
-    _adapter(surface[(method, version)]).validate_python(data, by_name=False)
+    validate_server_result(method, version, data, surface=surface)
     result: types.Result = _adapter(_monolith_row(monolith, method)).validate_python(data, by_name=False)
     return result