Protocol types for 2026-07-28: superset monolith, generated per-version packages, and wire-method maps

One public type set (mcp.types) covering every protocol revision through
2026-07-28; two per-version model packages generated from vendored
schema.json (scripts/gen_surface_types.py, --check enforced in CI) that
act as the schema-exact validating layer; and plain (method, version)
maps with two-step parse functions. Version gating is data: key absence
is the gate. Outbound serialization is the model dump, with the new
2026-07-28 result fields as ordinary serialized defaults.

Author: maxisbey

.github/workflows/shared.yml

@@ -30,6 +30,11 @@ jobs:
         env:
           SKIP: no-commit-to-branch,readme-v1-frozen
 
+      - name: Surface types match vendored schema
+        run: |
+          uv sync --group codegen --frozen
+          uv run --group codegen python scripts/gen_surface_types.py --check
+
       # TODO(Max): Drop this in v2. Deliberate updates (e.g. the v2 status
       # banner) go through the 'override-readme-freeze' label.
       - name: Check README.md is not modified

docs/migration.md

@@ -221,6 +221,10 @@ 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.
+
 ### `args` parameter removed from `ClientSessionGroup.call_tool()`
 
 The deprecated `args` parameter has been removed from `ClientSessionGroup.call_tool()`. Use `arguments` instead.
@@ -1181,7 +1185,7 @@ Behavior changes:
 
 ### Experimental Tasks support removed
 
-Tasks (SEP-1686) have been removed from the MCP specification and are no longer part of this SDK. The `mcp.client.experimental`, `mcp.server.experimental`, `mcp.shared.experimental`, and `mcp.server.lowlevel.experimental` modules have been removed, along with all `Task*` types, the `tasks` capability fields, `Tool.execution`, and the `experimental` properties on `ClientSession`, `ServerSession`, `Server`, and `ServerRequestContext`.
+Tasks (SEP-1686) have been removed from the MCP specification and are no longer part of this SDK. The `mcp.client.experimental`, `mcp.server.experimental`, `mcp.shared.experimental`, and `mcp.server.lowlevel.experimental` modules have been removed, along with the `experimental` properties on `ClientSession`, `ServerSession`, `Server`, and `ServerRequestContext`. The corresponding `Task*` types remain in `mcp.types` as types-only definitions.
 
 Tasks are expected to return as a separate MCP extension in a future release.
 
@@ -1227,6 +1231,10 @@ If you relied on extra fields round-tripping through MCP types, move that data i
 
 ## New Features
 
+### 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).
+
 ### `streamable_http_app()` available on lowlevel Server
 
 The `streamable_http_app()` method is now available directly on the lowlevel `Server` class, not just `MCPServer`. This allows using the streamable HTTP transport without the MCPServer wrapper.

pyproject.toml

@@ -104,6 +104,7 @@ docs = [
     "mkdocs-material[imaging]>=9.5.45",
     "mkdocstrings-python>=2.0.1",
 ]
+codegen = ["datamodel-code-generator==0.57.0"]
 
 [build-system]
 requires = ["hatchling", "uv-dynamic-versioning"]

schema/2025-11-25.json

@@ -0,0 +1,14 @@
+[
+  {
+    "protocol_version": "2025-11-25",
+    "source_path_in_spec_repo": "schema/2025-11-25/schema.json",
+    "spec_commit": "6d441518de8a9d5adbab0b10a76a667a63f90665",
+    "sha256": "4e01628360a2149892eab8f298ceee626d24a58862184eb8ec85d95b8f353e31"
+  },
+  {
+    "protocol_version": "2026-07-28",
+    "source_path_in_spec_repo": "schema/draft/schema.json",
+    "spec_commit": "6d441518de8a9d5adbab0b10a76a667a63f90665",
+    "sha256": "bce2e7c9622bb0b449475ba6d8d80228c71190a09250e75dabd502b280ecf3cb"
+  }
+]

schema/2026-07-28.json

@@ -0,0 +1,12 @@
+# Vendored protocol schemas
+
+JSON Schema files for each protocol version the SDK has a wire-shape surface
+package for, vendored from the [spec repository] at the commit recorded in
+`PINNED.json`. `scripts/gen_surface_types.py` reads these to regenerate
+`src/mcp/types/v<version>/__init__.py`; CI runs the generator with `--check`.
+
+To bump: drop the new `schema.json` here as `<protocol-version>.json`, update
+the matching entry in `PINNED.json` (commit + sha256), and run
+`uv run --group codegen python scripts/gen_surface_types.py`.
+
+[spec repository]: https://github.com/modelcontextprotocol/modelcontextprotocol