Keep the later-revision field drop private to the client session

The reported failure is on the client's inbound path, so the fix now
lives there as private helpers next to the existing inbound-ttl clamp
rather than as a new public function in mcp_types.methods.

Drop the exported strip_era_foreign_fields helper and the calls threaded
through the standalone parse functions and the server-side result
parsing (the server-side calls stripped nothing, since no client-result
method has a later-revision field). Restore the caching docs paragraph
and its docs test, which the client-local change does not contradict.

Author: maxisbey

docs/client/caching.md

@@ -101,7 +101,7 @@ Cache keys also carry the **server's identity**: the URL string you dialed, with
 
 The hints are also plain fields on every cacheable result (`result.ttl_ms` and `result.cache_scope`, already parsed), in case you want to layer your own bookkeeping on top of (or instead of) the built-in cache.
 
-Against an **older server** (pre-2026 protocol), the fields are outside that session's schema, so the models always show their conservative defaults: `ttl_ms == 0` and `cache_scope == "private"`, stale and unshared, the right assumption for a server that declared nothing. This holds even if a legacy server puts `ttlMs`/`cacheScope` keys on the wire anyway: those fields belong to a later protocol revision than the one negotiated, so the client drops them before parsing, and a smuggled hint (even a value the 2026-07-28 enum would reject) never reaches the model. The cache treats a legacy session the same way: hints are never consulted, only `default_ttl_ms` applies, and its default of `0` caches nothing, so a pre-2026 connection behaves exactly as it did before the cache existed.
+Against an **older server** (pre-2026 protocol), the fields are simply absent from the wire, and the models show their conservative defaults: `ttl_ms == 0` and `cache_scope == "private"`, stale and unshared, the right assumption for a server that declared nothing. The cache treats a legacy session the same way: hints are never consulted there (whatever keys appear on the wire), only `default_ttl_ms` applies, and its default of `0` caches nothing, so a pre-2026 connection behaves exactly as it did before the cache existed. If you need to distinguish "the server said 0" from "the server said nothing", check `"ttl_ms" in result.model_fields_set`: it's only set when the field actually arrived.
 
 ## Older clients
 

src/mcp-types/mcp_types/methods.py

@@ -45,7 +45,6 @@
     "parse_server_request",
     "parse_server_result",
     "serialize_server_result",
-    "strip_era_foreign_fields",
     "validate_client_notification",
     "validate_client_request",
     "validate_client_result",
@@ -632,67 +631,6 @@ def parse_server_notification(
     return _monolith_row(monolith, method).model_validate(_body(method, params), by_name=False)
 
 
-@cache
-def _wire_aliases(target: type[BaseModel] | UnionType) -> frozenset[str]:
-    """The top-level wire keys `target` declares (its members', for a union)."""
-    models: tuple[Any, ...] = get_args(target) if isinstance(target, UnionType) else (target,)
-    return frozenset(
-        field.alias or name
-        for model in models
-        if isinstance(model, type) and issubclass(model, BaseModel)
-        for name, field in model.model_fields.items()
-    )
-
-
-def _later_revision_fields(
-    method: str, version: str, surface: Mapping[tuple[str, str], type[BaseModel] | UnionType]
-) -> frozenset[str]:
-    """Wire keys a newer revision's surface declares for `method` but `version`'s does not.
-
-    Such a key is a later revision's field arriving on an earlier session
-    (e.g. 2026-07-28 `ttlMs`/`cacheScope` at 2025-11-25): outside that
-    session's contract, so it must not reach the version-free model, which
-    would otherwise apply the later revision's constraints to it. Only fields
-    a newer surface actually declares qualify - keys no surface knows
-    (extension payloads) and legal fields a strict surface merely omits
-    (e.g. `_meta` on an empty result) are never in this set.
-    """
-    later = KNOWN_PROTOCOL_VERSIONS[KNOWN_PROTOCOL_VERSIONS.index(version) + 1 :]
-    later_fields: set[str] = set()
-    for later_version in later:
-        row = surface.get((method, later_version))
-        if row is not None:
-            later_fields |= _wire_aliases(row)
-    return frozenset(later_fields) - _wire_aliases(surface[(method, version)])
-
-
-def strip_era_foreign_fields(
-    method: str,
-    version: str,
-    data: Mapping[str, Any],
-    *,
-    surface: Mapping[tuple[str, str], type[BaseModel] | UnionType] = SERVER_RESULTS,
-) -> Mapping[str, Any]:
-    """Drop a later revision's fields from a `version`-scoped result.
-
-    The version-free `mcp_types` models carry every revision's fields, so
-    parsing raw wire data into them lets a field of a revision newer than
-    `version` (and that revision's constraints) act on a session that never
-    negotiated it. This removes exactly those keys: the ones a newer surface
-    for `method` declares but `version`'s surface does not. Every other key
-    passes through untouched, so payloads the surface only gates (extension
-    result claims, open `_meta`) are unaffected, and on a session speaking the
-    newest revision the set is empty. Returns `data` itself when nothing is
-    stripped; an unknown `(method, version)` also returns `data` unchanged.
-    """
-    if version not in KNOWN_PROTOCOL_VERSIONS or (method, version) not in surface:
-        return data
-    foreign = _later_revision_fields(method, version, surface)
-    if foreign.isdisjoint(data):
-        return data
-    return {key: value for key, value in data.items() if key not in foreign}
-
-
 def serialize_server_result(
     method: str,
     version: str,
@@ -744,10 +682,6 @@ def parse_server_result(
 ) -> types.Result:
     """Validate a server result against `surface`, then parse and return its `monolith` model.
 
-    Cross-era fields (see `strip_era_foreign_fields`) are removed before the
-    monolith parse, so a later revision's field cannot reach the version-free
-    model on a session that did not negotiate it.
-
     Args:
         surface: `(method, version)` to wire-type map; the version-gate lookup
             and (per-schema-era) shape check run against this. Pass an extended
@@ -762,8 +696,7 @@ def parse_server_result(
         RuntimeError: surface matched but `method` has no monolith row.
     """
     validate_server_result(method, version, data, surface=surface)
-    payload = strip_era_foreign_fields(method, version, data, surface=surface)
-    result: types.Result = _adapter(_monolith_row(monolith, method)).validate_python(payload, by_name=False)
+    result: types.Result = _adapter(_monolith_row(monolith, method)).validate_python(data, by_name=False)
     return result
 
 
@@ -795,10 +728,6 @@ def parse_client_result(
 ) -> types.Result:
     """Validate a client result against `surface`, then parse and return its `monolith` model.
 
-    Cross-era fields (see `strip_era_foreign_fields`) are removed before the
-    monolith parse, so a later revision's field cannot reach the version-free
-    model on a session that did not negotiate it.
-
     Args:
         surface: `(method, version)` to wire-type map; the version-gate lookup
             and (per-schema-era) shape check run against this. Pass an extended
@@ -813,6 +742,5 @@ def parse_client_result(
         RuntimeError: surface matched but `method` has no monolith row.
     """
     validate_client_result(method, version, data, surface=surface)
-    payload = strip_era_foreign_fields(method, version, data, surface=surface)
-    result: types.Result = _adapter(_monolith_row(monolith, method)).validate_python(payload, by_name=False)
+    result: types.Result = _adapter(_monolith_row(monolith, method)).validate_python(data, by_name=False)
     return result

src/mcp/client/session.py

@@ -4,10 +4,10 @@
 import logging
 from collections.abc import Callable, Mapping, Sequence
 from dataclasses import dataclass
-from functools import reduce
+from functools import cache, reduce
 from operator import or_
-from types import TracebackType
-from typing import TYPE_CHECKING, Annotated, Any, Final, Literal, Protocol, TypeAlias, cast, overload
+from types import TracebackType, UnionType
+from typing import TYPE_CHECKING, Annotated, Any, Final, Literal, Protocol, TypeAlias, cast, get_args, overload
 
 import anyio
 import anyio.abc
@@ -30,6 +30,7 @@
 from mcp_types import methods as _methods
 from mcp_types.version import (
     HANDSHAKE_PROTOCOL_VERSIONS,
+    KNOWN_PROTOCOL_VERSIONS,
     LATEST_HANDSHAKE_VERSION,
     LATEST_MODERN_VERSION,
     MODERN_PROTOCOL_VERSIONS,
@@ -77,6 +78,39 @@ def _clamp_inbound_ttl(raw: dict[str, Any]) -> None:
         raw["ttlMs"] = 0
 
 
+@cache
+def _wire_fields(target: type[BaseModel] | UnionType) -> frozenset[str]:
+    """Top-level wire keys `target` declares (its members', for a union)."""
+    models: tuple[Any, ...] = get_args(target) if isinstance(target, UnionType) else (target,)
+    return frozenset(
+        field.alias or name
+        for model in models
+        if isinstance(model, type) and issubclass(model, BaseModel)
+        for name, field in model.model_fields.items()
+    )
+
+
+@cache
+def _later_revision_fields(method: str, version: str) -> frozenset[str]:
+    """Result keys a revision newer than `version` declares for `method` but `version` doesn't.
+
+    The version-free result types carry every revision's fields, so such a key
+    (e.g. 2026-07-28 `ttlMs`/`cacheScope` on a pre-2026 session) is outside the
+    negotiated contract yet would still parse into the model and trip that later
+    revision's constraints. Empty at the newest known revision.
+    """
+    current = _methods.SERVER_RESULTS.get((method, version))
+    if current is None or version not in KNOWN_PROTOCOL_VERSIONS:
+        return frozenset()
+    newer = KNOWN_PROTOCOL_VERSIONS[KNOWN_PROTOCOL_VERSIONS.index(version) + 1 :]
+    later: set[str] = set()
+    for revision in newer:
+        row = _methods.SERVER_RESULTS.get((method, revision))
+        if row is not None:
+            later |= _wire_fields(row)
+    return frozenset(later) - _wire_fields(current)
+
+
 def _same_schema(a: dict[str, Any] | None, b: dict[str, Any] | None) -> bool:
     """JSON equality for two output schemas.
 
@@ -558,13 +592,14 @@ async def send_request(
             _methods.validate_server_result(method, version, raw)
         except KeyError:
             pass
-        # A later revision's field (e.g. 2026-07-28 cache hints on a pre-2026
-        # session) is outside the negotiated contract and must not reach the
-        # version-free result type, which would apply that revision's constraints.
-        payload = _methods.strip_era_foreign_fields(method, version, raw)
+        # Drop a later revision's fields (e.g. 2026-07-28 cache hints on a pre-2026
+        # session): they are outside the negotiated contract, and the version-free
+        # result type would otherwise apply that revision's constraints to them.
+        if not (foreign := _later_revision_fields(method, version)).isdisjoint(raw):
+            raw = {key: value for key, value in raw.items() if key not in foreign}
         if isinstance(result_type, TypeAdapter):
-            return result_type.validate_python(payload, by_name=False)
-        return result_type.model_validate(payload, by_name=False)
+            return result_type.validate_python(raw, by_name=False)
+        return result_type.model_validate(raw, by_name=False)
 
     async def send_notification(self, notification: types.ClientNotification) -> None:
         """Send a one-way notification. Usable before entering the context manager.

src/mcp/server/connection.py

@@ -395,16 +395,8 @@ async def send_request(
                 _methods.validate_client_result(req.method, self.protocol_version, raw)
             except KeyError:
                 pass
-        # A later revision's field is outside the negotiated contract and must
-        # not reach the version-free result type.
-        payload = _methods.strip_era_foreign_fields(
-            req.method,
-            self.protocol_version,
-            raw,
-            surface=_methods.CLIENT_RESULTS,
-        )
         cls = result_type if result_type is not None else _RESULT_FOR[type(req)]
-        return cls.model_validate(payload, by_name=False)
+        return cls.model_validate(raw, by_name=False)
 
     async def notify(self, method: str, params: Mapping[str, Any] | None, opts: CallOptions | None = None) -> None:
         """Send a best-effort notification on the standalone stream.

src/mcp/server/session.py

@@ -119,15 +119,7 @@ async def send_request(
             _methods.validate_client_result(request.method, self.protocol_version, result)
         except KeyError:
             pass
-        # A later revision's field is outside the negotiated contract and must
-        # not reach the version-free result type.
-        payload = _methods.strip_era_foreign_fields(
-            request.method,
-            self.protocol_version,
-            result,
-            surface=_methods.CLIENT_RESULTS,
-        )
-        return result_type.model_validate(payload, by_name=False)
+        return result_type.model_validate(result, by_name=False)
 
     async def send_notification(
         self,

tests/docs_src/test_caching.py

@@ -199,3 +199,11 @@ async def test_a_custom_store_with_an_in_process_server_requires_target_id() ->
         "and Transport instances get a random per-client identity, so their entries in a shared store could "
         "never be served to another client"
     )
+
+
+async def test_the_wire_presence_check_the_page_recommends_works() -> None:
+    """The page's claim: `"ttl_ms" in result.model_fields_set` distinguishes a
+    server that sent the field from one that said nothing (model defaults)."""
+    async with Client(tutorial001.mcp) as client:
+        tools = await client.list_tools()
+    assert "ttl_ms" in tools.model_fields_set

tests/types/test_methods.py

@@ -682,45 +682,15 @@ def test_empty_result_body_parses_at_versions_that_define_it():
     assert isinstance(parsed, types.EmptyResult)
 
 
-def test_2026_07_28_result_fields_never_reach_the_model_at_earlier_versions():
-    """The negotiated surface is the version's contract: 2026-07-28 keys sent at an
-    earlier version are dropped there, so the model shows defaults, not the wire values."""
+def test_2026_07_28_shaped_result_extras_pass_at_earlier_versions():
+    """The earlier surface ignores unknown keys; the monolith preserves them on fields it declares."""
     parsed = methods.parse_server_result(
         "tools/list", "2025-11-25", {"tools": [], "resultType": "complete", "ttlMs": 5, "cacheScope": "public"}
     )
     assert isinstance(parsed, types.ListToolsResult)
-    assert (parsed.result_type, parsed.ttl_ms, parsed.cache_scope) == ("complete", 0, "private")
-    assert not {"ttl_ms", "cache_scope"} & parsed.model_fields_set
-
-
-def test_stripping_removes_only_later_revision_fields_and_nothing_at_the_newest_revision():
-    """Extension payload keys neither the model nor the schema declares pass through;
-    only the model's own fields from a later revision are stripped, and the newest
-    revision's surface declares them all, so it strips nothing."""
-    body: dict[str, Any] = {"tools": [], "ttlMs": 5, "cacheScope": "public", "vendor/x": 1}
-    assert methods.strip_era_foreign_fields("tools/list", "2025-11-25", body) == {"tools": [], "vendor/x": 1}
-    assert methods.strip_era_foreign_fields("tools/list", "2026-07-28", body) is body
-
-
-def test_a_legal_field_a_strict_surface_omits_is_not_a_later_revision_field():
-    """`ping` has no 2026-07-28 surface, so nothing is foreign at 2025-11-25: the
-    `_meta` its strict (empty-dumping) surface merely omits is a legal field, not a
-    later revision's, and it survives to the model."""
-    body: dict[str, Any] = {"_meta": {"trace": "t-1"}}
-    assert methods.strip_era_foreign_fields("ping", "2025-11-25", body) is body
-    parsed = methods.parse_server_result("ping", "2025-11-25", body)
-    assert isinstance(parsed, types.EmptyResult)
-    assert parsed.meta == {"trace": "t-1"}
-
-
-def test_a_2026_07_28_value_invalid_at_that_version_still_parses_at_earlier_versions():
-    """A pre-2026 result is judged only by its own schema, so a cache-hint value the
-    2026-07-28 enum rejects (a future or non-conformant server) cannot fail the parse."""
-    body: dict[str, Any] = {"tools": [], "resultType": "complete", "ttlMs": -1, "cacheScope": "session"}
-    parsed = methods.parse_server_result("tools/list", "2025-11-25", body)
-    assert isinstance(parsed, types.ListToolsResult)
-    with pytest.raises(pydantic.ValidationError):
-        methods.parse_server_result("tools/list", "2026-07-28", body)
+    assert parsed.result_type == "complete"
+    assert parsed.ttl_ms == 5
+    assert parsed.cache_scope == "public"
 
 
 def test_embedded_input_request_entries_without_method_reject_at_the_surface_step():