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. 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,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.

src/mcp/shared/version.py

@@ -16,6 +16,7 @@
     "2025-03-26",
     "2025-06-18",
     "2025-11-25",
+    "2026-07-28",
 )
 """Every released protocol revision, oldest to newest."""
 

src/mcp/types/__init__.py

@@ -1,22 +1,30 @@
 """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
 """
 
 # 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 +41,9 @@
     CreateMessageRequestParams,
     CreateMessageResult,
     CreateMessageResultWithTools,
+    CreateTaskResult,
+    DiscoverRequest,
+    DiscoverResult,
     ElicitationCapability,
     ElicitationRequiredErrorData,
     ElicitCompleteNotification,
@@ -49,6 +60,12 @@
     GetPromptRequest,
     GetPromptRequestParams,
     GetPromptResult,
+    GetTaskPayloadRequest,
+    GetTaskPayloadRequestParams,
+    GetTaskPayloadResult,
+    GetTaskRequest,
+    GetTaskRequestParams,
+    GetTaskResult,
     Icon,
     IconTheme,
     ImageContent,
@@ -58,6 +75,12 @@
     InitializeRequest,
     InitializeRequestParams,
     InitializeResult,
+    InputRequest,
+    InputRequests,
+    InputRequiredResult,
+    InputResponse,
+    InputResponseRequestParams,
+    InputResponses,
     ListPromptsRequest,
     ListPromptsResult,
     ListResourcesRequest,
@@ -66,12 +89,15 @@
     ListResourceTemplatesResult,
     ListRootsRequest,
     ListRootsResult,
+    ListTasksRequest,
+    ListTasksResult,
     ListToolsRequest,
     ListToolsResult,
     LoggingCapability,
     LoggingLevel,
     LoggingMessageNotification,
     LoggingMessageNotificationParams,
+    MissingRequiredClientCapabilityErrorData,
     ModelHint,
     ModelPreferences,
     Notification,
@@ -92,6 +118,7 @@
     ReadResourceRequest,
     ReadResourceRequestParams,
     ReadResourceResult,
+    RelatedTaskMetadata,
     Request,
     RequestParams,
     RequestParamsMeta,
@@ -105,6 +132,7 @@
     ResourceUpdatedNotification,
     ResourceUpdatedNotificationParams,
     Result,
+    ResultType,
     Role,
     Root,
     RootsCapability,
@@ -124,17 +152,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,9 +190,12 @@
     INTERNAL_ERROR,
     INVALID_PARAMS,
     INVALID_REQUEST,
+    JSONRPC_VERSION,
     METHOD_NOT_FOUND,
+    MISSING_REQUIRED_CLIENT_CAPABILITY,
     PARSE_ERROR,
     REQUEST_TIMEOUT,
+    UNSUPPORTED_PROTOCOL_VERSION,
     URL_ELICITATION_REQUIRED,
     ErrorData,
     JSONRPCError,
@@ -168,28 +211,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",
@@ -236,27 +292,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",
@@ -265,23 +334,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",
@@ -297,6 +378,10 @@
     "ResourceUpdatedNotification",
     "ResourceUpdatedNotificationParams",
     "RootsListChangedNotification",
+    "SubscriptionsAcknowledgedNotification",
+    "SubscriptionsAcknowledgedNotificationParams",
+    "TaskStatusNotification",
+    "TaskStatusNotificationParams",
     "ToolListChangedNotification",
     # Union types for request/response routing
     "ClientNotification",
@@ -317,9 +402,12 @@
     "INTERNAL_ERROR",
     "INVALID_PARAMS",
     "INVALID_REQUEST",
+    "JSONRPC_VERSION",
     "METHOD_NOT_FOUND",
+    "MISSING_REQUIRED_CLIENT_CAPABILITY",
     "PARSE_ERROR",
     "REQUEST_TIMEOUT",
+    "UNSUPPORTED_PROTOCOL_VERSION",
     "URL_ELICITATION_REQUIRED",
     "ErrorData",
     "JSONRPCError",