Move server identity to result _meta and stamp every 2026-era result (spec #3002)

The 2026-07-28 draft removed the serverInfo body field from DiscoverResult:
servers now report identity by stamping io.modelcontextprotocol/serverInfo
into every result's _meta (new ResultMetaObject type), and clients treat it
as optional, display-only metadata.

Server side:
- DiscoverResult loses server_info (monolith and generated surface); the
  default discover handler no longer passes identity.
- Every 2026-era result is stamped at the runner's single exit point, after
  the middleware chain, so custom methods, empty results, and middleware
  short-circuits are covered by construction. Stamping builds a shallow copy
  rather than mutating a dict the handler may retain, a handler-authored
  value wins, and the dumped stamp is cached per server. Notifications,
  error responses, and handshake-era results are never stamped.
- Opt-out per the spec's 'unless specifically configured not to do so':
  Server(include_server_info=False), also exposed on MCPServer.

Client side:
- ClientSession.server_info reads the discover result's _meta stamp, parsed
  once at adopt time; absent or malformed reads as None (the spec forbids
  acting on the value, so a bad stamp must not fail the connection). The
  wire surface keeps the field untyped for the same reason, via a
  shape-driven transform in the generator that stays lenient for future
  result-meta definitions.
- Client.server_info is now Implementation | None. This also fixes a live
  interop break: servers that already shipped the new shape omit the body
  field, which previously failed our discover validation and silently
  downgraded auto mode to the legacy handshake.

Tests: the interaction matrix runs with stamping off (the stamp would bake
the commit-dependent package version into every snapshot); stamping has
dedicated unit and wire-level coverage in tests/server/, and the tests that
exercise identity assert the new _meta form.

Author: maxisbey

docs_src/protocol_versions/tutorial004.py

@@ -16,4 +16,5 @@ async def main() -> None:
 
     async with Client(mcp, mode="2026-07-28", prior_discover=saved) as client:
         print(client.protocol_version)
-        print(client.server_info.name)
+        if client.server_info is not None:
+            print(client.server_info.name)

examples/stories/_harness.py

@@ -162,7 +162,7 @@ def run_client(main: Callable[..., Awaitable[None]]) -> None:
     if cfg["era"] == "dual-in-body":
         # The story pins its connection modes inside ``main`` itself, so hand it "auto"
         # (the ``Client`` default) and let those in-body pins decide. A hard version pin
-        # here would skip the discover probe and leave ``server_info`` blank.
+        # here would skip the discover probe and leave `server_info` None.
         era = "in-body"
     mode = {"modern": LATEST_MODERN_VERSION, "legacy": "legacy", "in-body": "auto"}[era]
 

examples/stories/dual_era/README.md

@@ -30,7 +30,9 @@ leg fails there today — run over `--http`.
   at construction; no date strings appear in the body.
 - `client.py` — `client.protocol_version` / `client.server_info` /
   `client.server_capabilities` are era-neutral: populated by `initialize` *or*
-  `server/discover`, whichever ran.
+  `server/discover`, whichever ran. On the 2026 era `server_info` comes from
+  the optional `serverInfo` `_meta` stamp (`None` for a server that does not
+  identify itself); `initialize` always carries it.
 - `server.py` — `ctx.request_context.protocol_version` is the era branch key
   (lowlevel: `ctx.protocol_version` directly). Compare against
   `MODERN_PROTOCOL_VERSIONS`, never a date literal.

examples/stories/dual_era/client.py

@@ -13,7 +13,11 @@ async def main(targets: TargetFactory, *, mode: str = "auto") -> None:
     # The version/info/capabilities accessors are era-neutral.
     async with Client(targets(), mode=mode) as modern:
         assert modern.protocol_version == LATEST_MODERN_VERSION
-        assert modern.server_info.name == "dual-era-example"
+        # On the 2026 era, server identity is an optional serverInfo stamp in the
+        # result _meta (None for an anonymous server); this server stamps it.
+        info = modern.server_info
+        assert info is not None, "the server stamps serverInfo into its results"
+        assert info.name == "dual-era-example"
         assert modern.server_capabilities.tools is not None
 
         listed = await modern.list_tools()
@@ -28,7 +32,9 @@ async def main(targets: TargetFactory, *, mode: str = "auto") -> None:
     # The same accessors are populated identically — here by ``initialize``.
     async with Client(targets(), mode="legacy") as legacy:
         assert legacy.protocol_version == LATEST_HANDSHAKE_VERSION
-        assert legacy.server_info.name == "dual-era-example"
+        info = legacy.server_info
+        assert info is not None, "initialize always carries serverInfo"
+        assert info.name == "dual-era-example"
         assert legacy.server_capabilities.tools is not None
 
         result = await legacy.call_tool("greet", {"name": "2025 client"})

examples/stories/reconnect/README.md

@@ -35,7 +35,7 @@ uv run python -m stories.reconnect.client --http --server server_lowlevel
 ## Caveats
 
 - `mode=<version-pin>` *without* `prior_discover=` synthesizes a placeholder
-  whose `server_info` is `Implementation(name="", version="")`. Pass the cached
+  with no `serverInfo` stamp, so `server_info` reads `None`. Pass the cached
   result to get real identity on reconnect. Whether `Client` should expose a
   public synthesizer (or refuse the bare pin) is open.
 - `client.session.discover_result` is a one-hop reach into the mechanics layer;

examples/stories/reconnect/client.py

@@ -15,7 +15,11 @@ async def main(targets: TargetFactory, *, mode: str = "auto") -> None:
         discovered = client.session.discover_result
         assert discovered is not None, "mode='auto' against a modern server populates discover_result"
         assert client.protocol_version == LATEST_MODERN_VERSION
-        assert client.server_info.name == "reconnect-example"
+        # On the 2026 era, server identity is an optional serverInfo stamp in the
+        # result _meta; an anonymous server reads as None. This one stamps it.
+        info = client.server_info
+        assert info is not None, "the server stamps serverInfo into its results"
+        assert info.name == "reconnect-example"
         assert LATEST_MODERN_VERSION in discovered.supported_versions
 
         result = await client.call_tool("add", {"a": 2, "b": 3})
@@ -28,11 +32,13 @@ async def main(targets: TargetFactory, *, mode: str = "auto") -> None:
 
     # Reconnect: a version pin plus the cached DiscoverResult adopts the prior state with
     # zero round-trips on entry. A Client cannot be re-entered after exit, so targets()
-    # yields a fresh one. Without prior_discover= a bare pin would synthesize a blank
-    # server_info — the cache is what makes the era-neutral accessors useful here.
+    # yields a fresh one. Without prior_discover= a bare pin would leave server_info
+    # None — the cache is what carries the server's identity stamp across reconnects.
     async with Client(targets(), mode=LATEST_MODERN_VERSION, prior_discover=rehydrated) as second:
         assert second.protocol_version == LATEST_MODERN_VERSION
-        assert second.server_info.name == "reconnect-example"
+        info = second.server_info
+        assert info is not None, "the cached DiscoverResult carries the serverInfo stamp"
+        assert info.name == "reconnect-example"
         assert second.server_capabilities.tools is not None
         assert second.session.discover_result == rehydrated
 

scripts/gen_surface_types.py

@@ -25,6 +25,10 @@
 SCHEMA_DIR = REPO_ROOT / "schema"
 TYPES_DIR = REPO_ROOT / "src" / "mcp-types" / "mcp_types"
 
+# The result-meta serverInfo stamp: every `$defs` entry carrying this property
+# gets its typed `$ref` stripped by `make_server_info_opaque` below.
+SERVER_INFO_META_PROPERTY = "io.modelcontextprotocol/serverInfo"
+
 # 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
@@ -129,9 +133,14 @@ def load_pinned() -> list[dict[str, str]]:
 
 
 def patch_schema(schema: dict[str, Any], patches: list[tuple[str, Any, Any]]) -> None:
-    """Apply `(path, old, new)` JSON-pointer-ish patches in place, asserting the old value."""
+    """Apply `(path, old, new)` JSON-pointer-ish patches in place, asserting the old value.
+
+    Path segments use JSON-pointer escaping (`~1` for `/`, `~0` for `~`) so keys
+    that themselves contain a slash (the reserved `io.modelcontextprotocol/*`
+    `_meta` keys) are addressable.
+    """
     for path, old, new in patches:
-        *parts, leaf = path.split("/")
+        *parts, leaf = (part.replace("~1", "/").replace("~0", "~") for part in path.split("/"))
         node: Any = schema
         for part in parts:
             node = node[int(part) if part.isdigit() else part]
@@ -140,6 +149,23 @@ def patch_schema(schema: dict[str, Any], patches: list[tuple[str, Any, Any]]) ->
         node[leaf] = new
 
 
+def make_server_info_opaque(schema: dict[str, Any]) -> None:
+    """Strip the typed `$ref` from every result-meta serverInfo property.
+
+    The stamp is display-only: the spec forbids acting on it, so a malformed
+    value must never fail a whole response (clients validate every inbound
+    result against this surface). Walking every `$defs` entry keeps future
+    result-meta definitions lenient by construction instead of relying on an
+    enumerated list; the typed, lenient parse happens at the read edge
+    (`ClientSession.server_info`). typescript-sdk does the same with a
+    schema-level catch-to-undefined.
+    """
+    for definition in schema.get("$defs", {}).values():
+        prop = definition.get("properties", {}).get(SERVER_INFO_META_PROPERTY)
+        if prop is not None and "$ref" in prop:
+            del prop["$ref"]
+
+
 def run_codegen(schema_path: Path, output_path: Path) -> None:
     """Run datamodel-code-generator at the version pinned in the `codegen` dependency group."""
     # fmt: off
@@ -197,6 +223,7 @@ def build(entry: dict[str, str]) -> str:
     version = entry["protocol_version"]
     schema = json.loads((SCHEMA_DIR / f"{version}.json").read_text())
     patch_schema(schema, SCHEMA_PATCHES.get(version, []))
+    make_server_info_opaque(schema)
 
     with tempfile.TemporaryDirectory() as tmp:
         patched = Path(tmp) / "schema.json"

src/mcp-types/mcp_types/__init__.py

@@ -12,6 +12,7 @@
     DEFAULT_NEGOTIATED_VERSION,
     LOG_LEVEL_META_KEY,
     PROTOCOL_VERSION_META_KEY,
+    SERVER_INFO_META_KEY,
     Annotations,
     AudioContent,
     BaseMetadata,
@@ -231,6 +232,8 @@
     "CLIENT_INFO_META_KEY",
     "CLIENT_CAPABILITIES_META_KEY",
     "LOG_LEVEL_META_KEY",
+    # Reserved result _meta keys
+    "SERVER_INFO_META_KEY",
     # Type aliases and variables
     "CORE_RESULT_TYPES",
     "ContentBlock",

src/mcp-types/mcp_types/_types.py

@@ -69,6 +69,13 @@ class MCPModel(BaseModel):
 introduces it. If absent, the server must not send log notifications.
 """
 
+SERVER_INFO_META_KEY = "io.modelcontextprotocol/serverInfo"
+"""Reserved result `_meta` key: the server `Implementation` (2026-07-28). SDK-managed.
+
+Servers SHOULD stamp it on every result. The value is self-reported and
+unverified - display, logging, and debugging only; never behavior or security.
+"""
+
 
 class RequestParamsMeta(TypedDict, extra_items=Any):
     """The `_meta` object on request params (schema name: `RequestMetaObject`).
@@ -591,8 +598,6 @@ class DiscoverResult(CacheableResult):
 
     capabilities: ServerCapabilities
 
-    server_info: Implementation
-
     instructions: str | None = None
     """Natural-language guidance describing the server and its features, e.g. for
     a system prompt. Should not duplicate information already in tool descriptions."""

src/mcp-types/mcp_types/v2026_07_28/__init__.py

@@ -743,9 +743,7 @@ class ResultMetaObject(WireModel):
     model_config = ConfigDict(
         extra="allow",
     )
-    io_modelcontextprotocol_server_info: Annotated[
-        Implementation | None, Field(alias="io.modelcontextprotocol/serverInfo")
-    ] = None
+    io_modelcontextprotocol_server_info: Annotated[Any | None, Field(alias="io.modelcontextprotocol/serverInfo")] = None
     """
     Identifies the server software producing the response. Servers SHOULD
     include this field on every response unless specifically configured not
@@ -901,9 +899,7 @@ class SubscriptionsListenResultMeta(WireModel):
     model_config = ConfigDict(
         extra="allow",
     )
-    io_modelcontextprotocol_server_info: Annotated[
-        Implementation | None, Field(alias="io.modelcontextprotocol/serverInfo")
-    ] = None
+    io_modelcontextprotocol_server_info: Annotated[Any | None, Field(alias="io.modelcontextprotocol/serverInfo")] = None
     """
     Identifies the server software producing the response. Servers SHOULD
     include this field on every response unless specifically configured not