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

docs/migration.md

@@ -221,6 +221,14 @@ 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
+
+Result types model the 2026-07-28 `resultType` and cache-directive fields as serialized defaults. Receivers 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.
+
+- Every concrete result serializes `"resultType": "complete"` (`"input_required"` for `InputRequiredResult`).
+- Cacheable results (`DiscoverResult`, `ListPromptsResult`, `ListResourcesResult`, `ListResourceTemplatesResult`, `ListToolsResult`, `ReadResourceResult`) also serialize `"ttlMs": 0` and `"cacheScope": "private"`.
+- `EmptyResult.result_type` defaults to `None` so `EmptyResult()` still dumps `{}` (some peer implementations reject extra keys on empty results); on a session negotiated at 2026-07-28 or later, construct `EmptyResult(result_type="complete")` explicitly.
+
 ### `args` parameter removed from `ClientSessionGroup.call_tool()`
 
 The deprecated `args` parameter has been removed from `ClientSessionGroup.call_tool()`. Use `arguments` instead.
@@ -1166,11 +1174,14 @@ 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 runtime removed; types remain
 
-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) runtime support has been removed: the `mcp.client.experimental`, `mcp.server.experimental`, `mcp.shared.experimental`, and `mcp.server.lowlevel.experimental` modules and the `experimental` properties on `ClientSession`, `ServerSession`, `Server`, and `ServerRequestContext` are gone. The `Task*` types, `tasks` capability subtrees, `Tool.execution`, and the `task` field on the task-augmentable params remain in `mcp.types` as types-only definitions:
 
-Tasks are expected to return as a separate MCP extension in a future release.
+- Attributes are snake_case (`task_id`, `created_at`), aliased to the camelCase wire names.
+- Timestamps are plain `str`, not `datetime`.
+- `GetTaskPayloadResult` retains only `_meta`; validate a `tasks/result` payload into the original request's result type instead.
+- Task methods are not members of the request/notification unions and `add_request_handler` does not dispatch them.
 
 ## Deprecations
 
@@ -1214,6 +1225,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`, `ttlMs`, and `cacheScope` defaults](#results-now-serialize-resulttype-ttlms-and-cachescope-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,8 +16,9 @@
     "2025-03-26",
     "2025-06-18",
     "2025-11-25",
+    "2026-07-28",
 )
-"""Every released protocol revision, oldest to newest."""
+"""Every protocol revision this SDK models, oldest to newest."""
 
 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,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,10 +190,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 +212,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 +293,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 +335,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 +379,10 @@
     "ResourceUpdatedNotification",
     "ResourceUpdatedNotificationParams",
     "RootsListChangedNotification",
+    "SubscriptionsAcknowledgedNotification",
+    "SubscriptionsAcknowledgedNotificationParams",
+    "TaskStatusNotification",
+    "TaskStatusNotificationParams",
     "ToolListChangedNotification",
     # Union types for request/response routing
     "ClientNotification",
@@ -318,10 +403,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",