Serialize spec results through the per-version surface schema

Generated surface types switch to extra="ignore" (with a per-version
allow-list for spec-declared open types: Result, _meta, GetTaskPayloadResult,
Tool input/output schemas, URLElicitationRequiredError data). The runner now
serializes spec-method results by dumping the monolith model and re-dumping
through the negotiated version's surface row, so 2026-only fields (resultType,
ttlMs, cacheScope) never reach the wire on a pre-2026 session.

- Monolith ttl_ms/cache_scope default to None; the SDK does not stamp a
  caching policy. EmptyResult.result_type stays None (deployed peer servers
  strict-validate ping responses).
- Spec methods absent at the negotiated version reject with METHOD_NOT_FOUND
  even if a handler is registered; custom methods fall through unchanged.
- Version fallback for pre-handshake/stateless is the literal 2025-11-25,
  not LATEST_PROTOCOL_VERSION.
- Add serialize_server_result to types.methods; codegen drift-guard asserts
  the open-class substitution count.
- Docstrings now say method-gating per version, shape per schema era.

Author: maxisbey

docs/migration.md

@@ -221,10 +221,6 @@ Common renames:
 
 Because `populate_by_name=True` is set, the old camelCase names still work as constructor kwargs (e.g., `Tool(inputSchema={...})` is accepted), but attribute access must use snake_case (`tool.input_schema`).
 
-### Results now serialize `resultType` and cache-directive defaults
-
-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.
@@ -1237,7 +1233,7 @@ If you relied on extra fields round-tripping through MCP types, move that data i
 
 ### 2025-11-25 and 2026-07-28 protocol fields modeled
 
-`mcp.types` models the 2025-11-25 and 2026-07-28 protocol fields (e.g. `resultType`, `ttlMs`/`cacheScope` on cacheable results, `inputResponses`/`requestState` on retried requests), so inbound payloads carrying these keys parse into typed fields and round-trip. Most are optional with `None` defaults; the result-directive fields carry serialized defaults - see [Results now serialize `resultType` and cache-directive defaults](#results-now-serialize-resulttype-and-cache-directive-defaults).
+`mcp.types` models the 2025-11-25 and 2026-07-28 protocol fields (e.g. `resultType`, `ttlMs`/`cacheScope` on cacheable results, `inputResponses`/`requestState` on retried requests), so inbound payloads carrying these keys parse into typed fields and round-trip. `ttlMs`/`cacheScope` default to `None`; `resultType` defaults to `"complete"` on concrete results (`None` on `EmptyResult`); the server strips all of them from the wire at pre-2026 versions.
 
 ### `streamable_http_app()` available on lowlevel Server
 

scripts/gen_surface_types.py

@@ -49,6 +49,16 @@
     ],
 }
 
+# Classes the spec defines as open key-value bags: `_meta` content, the
+# JSON-Schema-document fields on `Tool`, and the schemas with explicit
+# `additionalProperties: {}`. These keep `extra="allow"` so the sieve preserves
+# arbitrary keys; every other class ignores extras. Per-version because codegen
+# reuses class names across versions for unrelated schemas (e.g. `Data`).
+OPEN_CLASSES: dict[str, frozenset[str]] = {
+    "2025-11-25": frozenset({"Meta", "InputSchema", "OutputSchema", "Result", "GetTaskPayloadResult", "Data"}),
+    "2026-07-28": frozenset({"MetaObject", "RequestMetaObject", "InputSchema", "OutputSchema", "Result"}),
+}
+
 # Hand-written union aliases the wire-method maps reference by value; the schema
 # has no named definition for "everything tools/call may return", so name it here.
 EPILOGUES: dict[str, str] = {
@@ -109,7 +119,7 @@ def run_codegen(schema_path: Path, output_path: Path) -> None:
             "--use-annotated", "--use-field-description", "--use-schema-description",
             "--enum-field-as-literal", "all",
             "--use-union-operator", "--use-double-quotes",
-            "--extra-fields", "allow",
+            "--extra-fields", "ignore",
             # 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",
@@ -122,6 +132,29 @@ def run_codegen(schema_path: Path, output_path: Path) -> None:
         raise SystemExit(f"datamodel-codegen failed:\n{result.stderr}")
 
 
+def allow_open_class_extras(source: str, open_classes: frozenset[str]) -> str:
+    """Restore ``extra="allow"`` on ``open_classes`` only.
+
+    Every other class uses ``extra="ignore"`` so the surface acts as a sieve;
+    ``open_classes`` are the places the spec defines as open key-value bags.
+    """
+
+    def patch(match: re.Match[str]) -> str:
+        if match.group(1) not in open_classes:
+            return match.group(0)
+        return match.group(0).replace('extra="ignore"', 'extra="allow"')
+
+    source = re.sub(
+        r'^class (\w+)\(WireModel\):\n(?: {4}.*\n|\n)*? {4}model_config = ConfigDict\(\n {8}extra="ignore",\n {4}\)\n',
+        patch,
+        source,
+        flags=re.MULTILINE,
+    )
+    # Drift guard: substitution count must match the allow-list.
+    assert source.count('extra="allow"') == len(open_classes), (source.count('extra="allow"'), open_classes)
+    return source
+
+
 def build(entry: dict[str, str]) -> str:
     """Generate, post-process, and format one version's surface module text."""
     version = entry["protocol_version"]
@@ -137,6 +170,7 @@ def build(entry: dict[str, str]) -> str:
 
     source = re.sub(r"\A# generated by datamodel-codegen:\n#[^\n]*\n", "", source)
     source = re.sub(r"^class Model\(RootModel\[Any\]\):\n {4}root: Any\n+", "", source, count=1, flags=re.MULTILINE)
+    source = allow_open_class_extras(source, OPEN_CLASSES[version])
     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.

src/mcp/server/runner.py

@@ -219,19 +219,22 @@ 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
+        # 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.connection.protocol_version or "2025-11-25"
+        is_spec_method = method in _methods.MONOLITH_REQUESTS
 
         async def _inner() -> HandlerResult:
             # 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
+            # registered. Custom methods miss the monolith 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
+            if is_spec_method:
+                try:
+                    _methods.validate_client_request(method, version, params)
+                except KeyError:
+                    raise MCPError(code=METHOD_NOT_FOUND, message="Method not found", data=method) from None
             # 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.
@@ -259,15 +262,21 @@ 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
+        # TODO: reject resultType values outside {"complete", "input_required"} unless the
+        # corresponding extension is in this request's _meta clientCapabilities.extensions; the
+        # explicit MUST-reject is client-side (basic/index.mdx ResultType), this enforces it proactively.
+        if is_spec_method:
+            try:
+                result = _methods.serialize_server_result(method, version, result)
+            except KeyError:
+                # Middleware short-circuited a wrong-version spec method without
+                # calling `call_next`; it owns the result shape.
+                pass
+            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.
@@ -282,16 +291,18 @@ async def _on_notify(
     ) -> 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
+        version = self.connection.protocol_version or "2025-11-25"
 
         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 in _methods.MONOLITH_NOTIFICATIONS:
+                try:
+                    _methods.validate_client_notification(method, version, params)
+                except KeyError:
+                    logger.debug("dropped %r: not defined at %s", method, version)
+                    return
+                except ValidationError:
+                    logger.warning("dropped %r: malformed params", method)
+                    return
             if method == "notifications/initialized":
                 # Surface validation above already rejected a malformed body, so
                 # commit; fall through so a registered handler observes an

src/mcp/types/_types.py

@@ -185,16 +185,15 @@ class PaginatedResult(Result):
 class CacheableResult(Result):
     """Base class for results that carry client-side caching directives (2026-07-28).
 
-    Both fields are required on the 2026-07-28 wire and always serialized by
-    this SDK; older peers ignore the extra keys. The defaults are SDK choices
-    (the schema declares none).
+    Both fields are required on the 2026-07-28 wire; the SDK declares no
+    default, so a handler answering at 2026-07-28 must set them explicitly.
     """
 
-    ttl_ms: Annotated[int, Field(ge=0)] = 0
+    ttl_ms: Annotated[int, Field(ge=0)] | None = None
     """How long (ms) the client MAY cache this response, analogous to HTTP
     `Cache-Control: max-age`. 0 means immediately stale."""
 
-    cache_scope: Literal["public", "private"] = "private"
+    cache_scope: Literal["public", "private"] | None = None
     """Analogous to HTTP `Cache-Control: public` vs `private`: "public" allows
     shared caches to serve the response to any user; "private" forbids that."""
 
@@ -203,9 +202,10 @@ class EmptyResult(Result):
     """A result that indicates success but carries no data.
 
     `result_type` defaults to None so this dumps as `{}`: deployed TypeScript
-    and Rust SDK clients validate empty results strictly and reject extra keys.
-    The 2026-07-28 schema requires `resultType`, so code answering an empty
-    result on a 2026-07-28+ session must pass `result_type="complete"`.
+    and Rust SDK peers (clients and servers) validate empty results strictly
+    and reject extra keys. The 2026-07-28 schema requires `resultType`, so code
+    answering an empty result on a 2026-07-28+ session must pass
+    `result_type="complete"`.
     """
 
     result_type: ResultType | None = None

src/mcp/types/_wire_base.py

@@ -4,6 +4,6 @@
 
 
 class WireModel(BaseModel):
-    """Base for generated wire models: enables ``populate_by_name``; subclasses set ``extra="allow"`` themselves."""
+    """Base for generated wire models: enables ``populate_by_name``; subclasses set ``extra`` themselves."""
 
     model_config = ConfigDict(populate_by_name=True)

src/mcp/types/methods.py

@@ -1,8 +1,12 @@
-"""Per-version method maps and parse functions for inbound MCP traffic.
+"""Per-version method maps and parse/serialize functions for MCP traffic.
 
-Surface maps key `(method, version)` to schema-exact types (key absence is the
-version gate); monolith maps key `method` to the version-free `mcp.types` models
-user code receives. Session-layer wiring is a follow-up."""
+This module is supported public API; the `mcp.types.v*` packages it draws on
+are internal validators and not for direct import.
+
+Surface maps key `(method, version)` to per-version wire types (key absence is
+the version gate; shape validation is per schema era, i.e. 2025-11-25 for every
+pre-2026 version and 2026-07-28 for 2026). Monolith maps key `method` to the
+version-free `mcp.types` models user code receives."""
 
 from __future__ import annotations
 
@@ -34,6 +38,7 @@
     "parse_server_notification",
     "parse_server_request",
     "parse_server_result",
+    "serialize_server_result",
     "validate_client_notification",
     "validate_client_request",
     "validate_server_result",
@@ -459,9 +464,9 @@ def parse_client_request(
     """Validate a client request against `surface`, then parse and return its `monolith` model.
 
     Args:
-        surface: `(method, version)` to schema-exact type map; the version-gate
-            lookup and shape check run against this. Pass an extended map to
-            admit custom methods.
+        surface: `(method, version)` to wire-type map; the version-gate lookup
+            and (per-schema-era) shape check run against this. Pass an extended
+            map to admit custom methods.
         monolith: `method` to version-free model map; the returned instance is
             parsed from this row. Must cover every method `surface` admits.
 
@@ -486,9 +491,9 @@ def parse_server_request(
     """Validate a server request against `surface`, then parse and return its `monolith` model.
 
     Args:
-        surface: `(method, version)` to schema-exact type map; the version-gate
-            lookup and shape check run against this. Pass an extended map to
-            admit custom methods.
+        surface: `(method, version)` to wire-type map; the version-gate lookup
+            and (per-schema-era) shape check run against this. Pass an extended
+            map to admit custom methods.
         monolith: `method` to version-free model map; the returned instance is
             parsed from this row. Must cover every method `surface` admits.
 
@@ -533,9 +538,9 @@ def parse_client_notification(
     """Validate a client notification against `surface`, then parse and return its `monolith` model.
 
     Args:
-        surface: `(method, version)` to schema-exact type map; the version-gate
-            lookup and shape check run against this. Pass an extended map to
-            admit custom methods.
+        surface: `(method, version)` to wire-type map; the version-gate lookup
+            and (per-schema-era) shape check run against this. Pass an extended
+            map to admit custom methods.
         monolith: `method` to version-free model map; the returned instance is
             parsed from this row. Must cover every method `surface` admits.
 
@@ -560,9 +565,9 @@ def parse_server_notification(
     """Validate a server notification against `surface`, then parse and return its `monolith` model.
 
     Args:
-        surface: `(method, version)` to schema-exact type map; the version-gate
-            lookup and shape check run against this. Pass an extended map to
-            admit custom methods.
+        surface: `(method, version)` to wire-type map; the version-gate lookup
+            and (per-schema-era) shape check run against this. Pass an extended
+            map to admit custom methods.
         monolith: `method` to version-free model map; the returned instance is
             parsed from this row. Must cover every method `surface` admits.
 
@@ -578,6 +583,30 @@ def parse_server_notification(
     return _monolith_row(monolith, method).model_validate(_body(method, params), by_name=False)
 
 
+def serialize_server_result(
+    method: str,
+    version: str,
+    data: Mapping[str, Any],
+    *,
+    surface: Mapping[tuple[str, str], type[BaseModel] | UnionType] = SERVER_RESULTS,
+) -> dict[str, Any]:
+    """Validate `data` against `surface` and return its surface-shaped dump.
+
+    The surface model carries `extra="ignore"`, so fields not in `version`'s
+    schema are dropped from the returned dict.
+
+    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 = _adapter(surface[(method, version)])
+    return adapter.dump_python(
+        adapter.validate_python(data, by_name=False), by_alias=True, mode="json", exclude_none=True
+    )
+
+
 def validate_server_result(
     method: str,
     version: str,
@@ -592,8 +621,7 @@ def validate_server_result(
         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)
+    serialize_server_result(method, version, data, surface=surface)
 
 
 def parse_server_result(
@@ -607,9 +635,9 @@ def parse_server_result(
     """Validate a server result against `surface`, then parse and return its `monolith` model.
 
     Args:
-        surface: `(method, version)` to schema-exact type map; the version-gate
-            lookup and shape check run against this. Pass an extended map to
-            admit custom methods.
+        surface: `(method, version)` to wire-type map; the version-gate lookup
+            and (per-schema-era) shape check run against this. Pass an extended
+            map to admit custom methods.
         monolith: `method` to version-free model map; the returned instance is
             parsed from this row. Must cover every method `surface` admits.
 
@@ -635,9 +663,9 @@ def parse_client_result(
     """Validate a client result against `surface`, then parse and return its `monolith` model.
 
     Args:
-        surface: `(method, version)` to schema-exact type map; the version-gate
-            lookup and shape check run against this. Pass an extended map to
-            admit custom methods.
+        surface: `(method, version)` to wire-type map; the version-gate lookup
+            and (per-schema-era) shape check run against this. Pass an extended
+            map to admit custom methods.
         monolith: `method` to version-free model map; the returned instance is
             parsed from this row. Must cover every method `surface` admits.