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

One public type set (mcp.types) covering every protocol revision through
2026-07-28, two committed per-version model packages that act as the
schema-exact validating layer, and plain (method, version) maps with
two-step parse functions replacing the previous serializer boundary.
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

docs/migration.md

@@ -221,6 +221,20 @@ 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`, `ttlMs`, and `cacheScope` defaults
+
+The 2026-07-28 protocol revision requires every result to carry a `resultType` member and adds cache directives to the cacheable results. The v2 result types model these as fields with serialized defaults rather than `None`-defaulted optional fields, so serialized results now always include them:
+
+- `CallToolResult`, `CompleteResult`, `DiscoverResult`, `GetPromptResult`, `ListPromptsResult`, `ListResourcesResult`, `ListResourceTemplatesResult`, `ListToolsResult`, and `ReadResourceResult` serialize `"resultType": "complete"`.
+- `InputRequiredResult` serializes `"resultType": "input_required"`.
+- The cacheable results (`DiscoverResult`, `ListPromptsResult`, `ListResourcesResult`, `ListResourceTemplatesResult`, `ListToolsResult`, `ReadResourceResult`) also serialize `"ttlMs": 0` and `"cacheScope": "private"`.
+
+Modeling these as defaults keeps a single set of result types valid across protocol versions without the wire layer injecting fields at serialization time.
+
+In v1 these keys never appeared in serialized results. Receivers ignore unknown result fields, so the added keys interoperate with peers on any protocol version, but tests or recorded fixtures that compare exact serialized result payloads need the new keys added.
+
+`EmptyResult` is the deliberate exception: its `result_type` defaults to `None`, so `EmptyResult()` still dumps `{}`. Several deployed SDK implementations validate empty results strictly and reject unexpected keys, so the SDK never volunteers `resultType` on an empty result. Code answering with an empty result on a session negotiated at 2026-07-28 or later must construct `EmptyResult(result_type="complete")` explicitly (use `mcp.shared.version.is_version_at_least` for the floor check).
+
 ### `args` parameter removed from `ClientSessionGroup.call_tool()`
 
 The deprecated `args` parameter has been removed from `ClientSessionGroup.call_tool()`. Use `arguments` instead.
@@ -1166,11 +1180,18 @@ In practice, replace direct `ServerSession` use with `Server.run(read_stream, wr
 
 `BaseSession` is still used by `ClientSession`, which never relied on these members. `RequestResponder.respond()` is unchanged.
 
-### Experimental Tasks support removed
+### Experimental Tasks support removed (types restored, types-only)
+
+Tasks (SEP-1686) runtime support has been removed from this SDK. The `mcp.client.experimental`, `mcp.server.experimental`, `mcp.shared.experimental`, and `mcp.server.lowlevel.experimental` modules are gone, along with the `experimental` properties on `ClientSession`, `ServerSession`, `Server`, and `ServerRequestContext`.
+
+The 2025-11-25 protocol *types* are back in `mcp.types` so that 2025-11-25 task payloads can still be modeled: the `Task*` types, the `tasks` capability subtrees, `Tool.execution`, and the `task` field on the four task-augmentable params classes. They are types-only definitions:
 
-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`.
+- Attributes are snake_case (`task_id`, `created_at`), aliased to the camelCase wire names.
+- Timestamps are plain `str` values, not `datetime`.
+- `GetTaskPayloadResult` follows the default extra-field policy (`ignore`), so it retains only `_meta`; validate a tasks/result payload into the original request's result type instead.
+- None of the task methods is a member of the request/notification unions, and `add_request_handler` does not dispatch them.
 
-Tasks are expected to return as a separate MCP extension in a future release.
+Tasks runtime support is expected to return as a separate MCP extension in a future release.
 
 ## Deprecations
 
@@ -1214,6 +1235,10 @@ If you relied on extra fields round-tripping through MCP types, move that data i
 
 ## New Features
 
+### Newer protocol fields are modeled and retained
+
+`mcp.types` now models the 2025-11-25 and 2026-07-28 protocol fields and types (for example `resultType`, `ttlMs`/`cacheScope` on the cacheable results, and `inputResponses`/`requestState` on retried requests). Inbound payloads carrying these keys used to lose them to the unknown-field policy on re-dump; they now parse into typed fields and survive a user-level round-trip. Most of the new fields are optional with `None` defaults, so dumps of values that do not set them are unchanged; the result directive fields (`resultType`, `ttlMs`, `cacheScope`) instead carry serialized defaults — see [Results now serialize `resultType`, `ttlMs`, and `cacheScope` defaults](#results-now-serialize-resulttype-ttlms-and-cachescope-defaults) under Breaking Changes.
+
 ### `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.

src/mcp/shared/version.py

@@ -16,8 +16,13 @@
     "2025-03-26",
     "2025-06-18",
     "2025-11-25",
+    "2026-07-28",
 )
-"""Every released protocol revision, oldest to newest."""
+"""Every protocol revision this SDK knows, oldest to newest.
+
+Knowing a revision (its types and wire shapes are modeled) is independent of
+being able to negotiate it; see SUPPORTED_PROTOCOL_VERSIONS for the latter.
+"""
 
 SUPPORTED_PROTOCOL_VERSIONS: list[str] = ["2024-11-05", "2025-03-26", "2025-06-18", LATEST_PROTOCOL_VERSION]
 """Protocol revisions this SDK can negotiate."""

src/mcp/types/__init__.py

@@ -1,22 +1,35 @@
 """This module defines the types for the MCP protocol.
 
 Check the latest schema at:
-https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/schema/2025-11-25/schema.json
+https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/schema/draft/schema.json
+
+The models here are the version-superset types user code works with; the
+schema-exact wire shapes live in the surface packages
+(``mcp.types.v2025_11_25``, which serves every protocol version through
+2025-11-25, and ``mcp.types.v2026_07_28``).
 """
 
 # Re-export everything from _types for backward compatibility
 from mcp.types._types import (
+    CLIENT_CAPABILITIES_META_KEY,
+    CLIENT_INFO_META_KEY,
     DEFAULT_NEGOTIATED_VERSION,
     LATEST_PROTOCOL_VERSION,
+    LOG_LEVEL_META_KEY,
+    PROTOCOL_VERSION_META_KEY,
     Annotations,
     AudioContent,
     BaseMetadata,
     BlobResourceContents,
+    CacheableResult,
     CallToolRequest,
     CallToolRequestParams,
     CallToolResult,
     CancelledNotification,
     CancelledNotificationParams,
+    CancelTaskRequest,
+    CancelTaskRequestParams,
+    CancelTaskResult,
     ClientCapabilities,
     ClientNotification,
     ClientRequest,
@@ -33,6 +46,9 @@
     CreateMessageRequestParams,
     CreateMessageResult,
     CreateMessageResultWithTools,
+    CreateTaskResult,
+    DiscoverRequest,
+    DiscoverResult,
     ElicitationCapability,
     ElicitationRequiredErrorData,
     ElicitCompleteNotification,
@@ -49,6 +65,12 @@
     GetPromptRequest,
     GetPromptRequestParams,
     GetPromptResult,
+    GetTaskPayloadRequest,
+    GetTaskPayloadRequestParams,
+    GetTaskPayloadResult,
+    GetTaskRequest,
+    GetTaskRequestParams,
+    GetTaskResult,
     Icon,
     IconTheme,
     ImageContent,
@@ -58,6 +80,12 @@
     InitializeRequest,
     InitializeRequestParams,
     InitializeResult,
+    InputRequest,
+    InputRequests,
+    InputRequiredResult,
+    InputResponse,
+    InputResponseRequestParams,
+    InputResponses,
     ListPromptsRequest,
     ListPromptsResult,
     ListResourcesRequest,
@@ -66,12 +94,15 @@
     ListResourceTemplatesResult,
     ListRootsRequest,
     ListRootsResult,
+    ListTasksRequest,
+    ListTasksResult,
     ListToolsRequest,
     ListToolsResult,
     LoggingCapability,
     LoggingLevel,
     LoggingMessageNotification,
     LoggingMessageNotificationParams,
+    MissingRequiredClientCapabilityErrorData,
     ModelHint,
     ModelPreferences,
     Notification,
@@ -92,6 +123,7 @@
     ReadResourceRequest,
     ReadResourceRequestParams,
     ReadResourceResult,
+    RelatedTaskMetadata,
     Request,
     RequestParams,
     RequestParamsMeta,
@@ -105,6 +137,7 @@
     ResourceUpdatedNotification,
     ResourceUpdatedNotificationParams,
     Result,
+    ResultType,
     Role,
     Root,
     RootsCapability,
@@ -124,17 +157,29 @@
     StopReason,
     SubscribeRequest,
     SubscribeRequestParams,
+    SubscriptionFilter,
+    SubscriptionsAcknowledgedNotification,
+    SubscriptionsAcknowledgedNotificationParams,
+    SubscriptionsListenRequest,
+    SubscriptionsListenRequestParams,
+    Task,
+    TaskMetadata,
+    TaskStatus,
+    TaskStatusNotification,
+    TaskStatusNotificationParams,
     TextContent,
     TextResourceContents,
     Tool,
     ToolAnnotations,
     ToolChoice,
+    ToolExecution,
     ToolListChangedNotification,
     ToolResultContent,
     ToolsCapability,
     ToolUseContent,
     UnsubscribeRequest,
     UnsubscribeRequestParams,
+    UnsupportedProtocolVersionErrorData,
     UrlElicitationCapability,
     client_notification_adapter,
     client_request_adapter,
@@ -150,10 +195,13 @@
     INTERNAL_ERROR,
     INVALID_PARAMS,
     INVALID_REQUEST,
+    JSONRPC_VERSION,
     METHOD_NOT_FOUND,
+    MISSING_REQUIRED_CLIENT_CAPABILITY,
     PARSE_ERROR,
     REQUEST_CANCELLED,
     REQUEST_TIMEOUT,
+    UNSUPPORTED_PROTOCOL_VERSION,
     URL_ELICITATION_REQUIRED,
     ErrorData,
     JSONRPCError,
@@ -169,28 +217,41 @@
     # Protocol version constants
     "LATEST_PROTOCOL_VERSION",
     "DEFAULT_NEGOTIATED_VERSION",
+    # Reserved request _meta keys
+    "PROTOCOL_VERSION_META_KEY",
+    "CLIENT_INFO_META_KEY",
+    "CLIENT_CAPABILITIES_META_KEY",
+    "LOG_LEVEL_META_KEY",
     # Type aliases and variables
     "ContentBlock",
     "ElicitRequestedSchema",
     "ElicitRequestParams",
     "IncludeContext",
+    "InputRequest",
+    "InputRequests",
+    "InputResponse",
+    "InputResponses",
     "LoggingLevel",
     "ProgressToken",
+    "ResultType",
     "Role",
     "SamplingContent",
     "SamplingMessageContentBlock",
     "StopReason",
+    "TaskStatus",
     # Base classes
     "BaseMetadata",
     "Request",
     "Notification",
     "Result",
     "RequestParams",
     "RequestParamsMeta",
+    "InputResponseRequestParams",
     "NotificationParams",
     "PaginatedRequest",
     "PaginatedRequestParams",
     "PaginatedResult",
+    "CacheableResult",
     "EmptyResult",
     # Capabilities
     "ClientCapabilities",
@@ -237,27 +298,40 @@
     "ResourceTemplateReference",
     "Root",
     "SamplingMessage",
+    "SubscriptionFilter",
+    "Task",
+    "TaskMetadata",
+    "RelatedTaskMetadata",
     "Tool",
     "ToolAnnotations",
     "ToolChoice",
+    "ToolExecution",
     # Requests
     "CallToolRequest",
     "CallToolRequestParams",
     "CompleteRequest",
     "CompleteRequestParams",
+    "CancelTaskRequest",
+    "CancelTaskRequestParams",
     "CreateMessageRequest",
     "CreateMessageRequestParams",
+    "DiscoverRequest",
     "ElicitRequest",
     "ElicitRequestFormParams",
     "ElicitRequestURLParams",
     "GetPromptRequest",
     "GetPromptRequestParams",
+    "GetTaskPayloadRequest",
+    "GetTaskPayloadRequestParams",
+    "GetTaskRequest",
+    "GetTaskRequestParams",
     "InitializeRequest",
     "InitializeRequestParams",
     "ListPromptsRequest",
     "ListResourcesRequest",
     "ListResourceTemplatesRequest",
     "ListRootsRequest",
+    "ListTasksRequest",
     "ListToolsRequest",
     "PingRequest",
     "ReadResourceRequest",
@@ -266,23 +340,35 @@
     "SetLevelRequestParams",
     "SubscribeRequest",
     "SubscribeRequestParams",
+    "SubscriptionsListenRequest",
+    "SubscriptionsListenRequestParams",
     "UnsubscribeRequest",
     "UnsubscribeRequestParams",
     # Results
     "CallToolResult",
+    "CancelTaskResult",
     "CompleteResult",
     "CreateMessageResult",
     "CreateMessageResultWithTools",
+    "CreateTaskResult",
+    "DiscoverResult",
     "ElicitResult",
     "ElicitationRequiredErrorData",
     "GetPromptResult",
+    "GetTaskPayloadResult",
+    "GetTaskResult",
     "InitializeResult",
+    "InputRequiredResult",
     "ListPromptsResult",
     "ListResourcesResult",
     "ListResourceTemplatesResult",
     "ListRootsResult",
+    "ListTasksResult",
     "ListToolsResult",
     "ReadResourceResult",
+    # Error data payloads
+    "MissingRequiredClientCapabilityErrorData",
+    "UnsupportedProtocolVersionErrorData",
     # Notifications
     "CancelledNotification",
     "CancelledNotificationParams",
@@ -298,6 +384,10 @@
     "ResourceUpdatedNotification",
     "ResourceUpdatedNotificationParams",
     "RootsListChangedNotification",
+    "SubscriptionsAcknowledgedNotification",
+    "SubscriptionsAcknowledgedNotificationParams",
+    "TaskStatusNotification",
+    "TaskStatusNotificationParams",
     "ToolListChangedNotification",
     # Union types for request/response routing
     "ClientNotification",
@@ -318,10 +408,13 @@
     "INTERNAL_ERROR",
     "INVALID_PARAMS",
     "INVALID_REQUEST",
+    "JSONRPC_VERSION",
     "METHOD_NOT_FOUND",
+    "MISSING_REQUIRED_CLIENT_CAPABILITY",
     "PARSE_ERROR",
     "REQUEST_CANCELLED",
     "REQUEST_TIMEOUT",
+    "UNSUPPORTED_PROTOCOL_VERSION",
     "URL_ELICITATION_REQUIRED",
     "ErrorData",
     "JSONRPCError",