Let a legacy-era tools/call answer with a CreateTaskResult

SEP-1686 makes a task-augmented `tools/call` answer with a `CreateTaskResult`,
but the `tools/call` result rows held `CallToolResult` alone. The request half
shipped and the response half did not, so a server returning a task got
`-32603 "Handler returned an invalid result"`, a server returning both shapes
had `task` silently sieved away, and a client receiving one raised
`ValidationError` before its caller saw anything. The v1.x line could express
that response; v2 cannot, on a revision the SDK still negotiates and still lets
a server advertise `capabilities.tasks` for.

Give the row its second arm as a generated `AnyCallToolResult`, alongside the
2026 aliases, and widen the lowlevel `Server`'s `on_call_tool` to match. Return
types are covariant, so a handler that only returns `CallToolResult` is
unaffected. All four pre-2026 versions get the arm, because all four share
`v2025.CallToolRequest` and therefore already parse `params.task`: answering it
at one of them and not the others is the same incoherence one version along.

`Task.ttl` is required and nullable ("null for unlimited"), and every dump path
passes `exclude_none=True`, which cannot tell a required null from an unset
optional and dropped it, leaving a body that fails the surface it was just
validated against. Rather than patch the 27 dump sites, models carrying such a
field now take a `KeepRequiredNullable` base that puts it back, and only that:
a field the caller filtered out with `include`/`exclude`, or one that was never
set, stays absent. The generator derives which classes need it from the schema
and a test asserts the same rule against the built models, so a nullable-required
field in a future revision is covered without anyone remembering.

That rule also reaches two live bugs of the same shape.
`LoggingMessageNotificationParams.data` is required and untyped, so
`ctx.log("info", None)` dropped the key and the receiving session rejected the
notification before dispatch: the message vanished with no error to either side,
at every protocol version. And `JSONRPCError.id` is required-and-nullable per
JSON-RPC 2.0, which the streamable-HTTP writer worked around by hand at one call
site; that patch is deleted and the base covers every writer.

The base is applied per model rather than to `MCPModel`/`WireModel`: a wrap
serializer costs per dump and pushes pydantic off its fast path for every model
in the tree, which measured 5x on a 20-tool `tools/list`. Its return is
deliberately unannotated, because an annotation there collapses the model's
serialization JSON schema to an opaque object.

The `tasks/*` lifecycle methods are left where they already work. They are
absent from `SPEC_CLIENT_METHODS`, so `Server.add_request_handler` serves them
today; adding registry rows would put those names into that version-flattened
set, which would make it illegal for an extension to bind `tasks/get` and would
gate the 2026 tasks extension's own calls to METHOD_NOT_FOUND. 2026-07-28 keeps
rejecting a `CreateTaskResult` on `tools/call`, which is correct: tasks left the
core protocol there.

Author: maxisbey

docs/advanced/low-level-server.md

@@ -185,6 +185,7 @@ The handshake belongs to the runner. `server/discover`, `ping`, and every other
 Each of these is one idea you now have the vocabulary for; each has its own page.
 
 * `on_call_tool`, `on_get_prompt`, and `on_read_resource` may return an `InputRequiredResult` instead of their normal result to pause the call and ask the client for input; see **[Multi-round-trip requests](../handlers/multi-round-trip.md)**. True to this tier, nothing is installed for you: where `MCPServer` seals `requestState` by default, here the `request_state` you set crosses the wire exactly as written until you opt in with `server.middleware.append(RequestStateBoundary(RequestStateSecurity(keys=[...]), default_audience=server.name))`: one line (both names import from `mcp.server.request_state`) for the identical sealing and verification `MCPServer` performs (**[Protecting `requestState`](../handlers/multi-round-trip.md#protecting-requeststate)**).
+* `on_call_tool` may also return a `CreateTaskResult` to answer a task-augmented call on a handshake-era connection, which is the one piece of SEP-1686 the SDK still carries; the store and the `tasks/*` handlers are yours to bring, and the 2026-07-28 revision rejects the shape because tasks left its core protocol. See **[Experimental Tasks runtime removed](../migration.md#experimental-tasks-runtime-removed)**.
 * `on_list_resources`, `on_read_resource`, `on_list_prompts`, `on_get_prompt`, `on_completion` are the same `(ctx, params) -> result` shape for the other primitives.
 * `on_subscriptions_listen` serves the 2026-07-28 `subscriptions/listen` stream. Pass a `ListenHandler` built over a `SubscriptionBus` and publish events to the bus from your other handlers; see **[Subscriptions](../handlers/subscriptions.md)** for the full composition.
 * `server.streamable_http_app()` returns the same Starlette app `MCPServer`'s does; deploy it the way **[Running your server](../run/index.md)** deploys any other ASGI app. There is no `server.run(transport=...)` down here: `server.run(read_stream, write_stream, server.create_initialization_options())` drives one connection over a pair of streams, and that one line is the whole story.

docs/migration.md

@@ -33,7 +33,7 @@ Every section heading below names the API it affects, so searching this page for
 | pin dependencies or use the `mcp` CLI | [Packaging, dependencies, and CLI](#packaging-dependencies-and-cli) |
 | import `mcp.types` or touch protocol types (everyone does) | [Types and wire format](#types-and-wire-format) |
 | run `FastMCP`/`MCPServer` servers | [MCPServer (formerly FastMCP)](#mcpserver-formerly-fastmcp) |
-| use the lowlevel `Server` | [Lowlevel Server](#lowlevel-server), plus [Timeouts take `float` seconds](#timeouts-take-float-seconds-instead-of-timedelta) and [Experimental Tasks support removed](#experimental-tasks-support-removed) under Clients |
+| use the lowlevel `Server` | [Lowlevel Server](#lowlevel-server), plus [Timeouts take `float` seconds](#timeouts-take-float-seconds-instead-of-timedelta) and [Experimental Tasks runtime removed](#experimental-tasks-runtime-removed) under Clients |
 | write client code with `Client` or `ClientSession` | [Clients](#clients), plus [`streamablehttp_client` removed](#streamablehttp_client-removed) under Transports |
 | use stdio or streamable HTTP directly, or maintain a custom transport | [Transports](#transports) |
 | maintain OAuth client auth or a protected server | [OAuth and server auth](#oauth-and-server-auth) |
@@ -1653,11 +1653,62 @@ Behavior changes:
 
 `mcp.shared.session` is now a compatibility module: `ProgressFnT` is re-exported (its home is `mcp.shared.dispatcher`), and `RequestResponder` remains as a typing-only stub so `MessageHandlerFnT` annotations keep importing. `RequestResponder.respond()` no longer exists, and neither do the cancellation-tracking members (`cancel()`, the `cancelled` and `in_flight` properties, the `on_complete` constructor argument) or `BaseSession._in_flight`; inbound cancellation is handled by `JSONRPCDispatcher`.
 
-### Experimental Tasks support removed
+### Experimental Tasks runtime removed
 
-Tasks ([SEP-1686](https://github.com/modelcontextprotocol/modelcontextprotocol/issues/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, except the `TaskExecutionMode` alias, whose literal is now inlined on `ToolExecution.task_support`.
+The task runtime that shipped behind the `experimental` properties is gone. 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`. There is no built-in task store, no polling helper, and no automatic `tasks/*` routing. The `TaskExecutionMode` alias is also gone; its literal is inlined on `ToolExecution.task_support`.
 
-The 2026-07-28 revision reintroduces Tasks as an official extension: [SEP-2663](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2663), `io.modelcontextprotocol/tasks`, redesigned around polling (`tasks/get`) instead of a blocking `tasks/result`. This SDK does not implement the extension yet.
+The task types stay, so a server can still serve Tasks ([SEP-1686](https://github.com/modelcontextprotocol/modelcontextprotocol/issues/1686)) on a handshake-era connection by supplying the parts the runtime used to provide. This covers the server side of a task-augmented `tools/call`; the client side of a task-augmented `sampling/createMessage` or `elicitation/create` is not wired, so a client cannot answer one of those with a `CreateTaskResult`. A task-augmented `tools/call` arrives with `params.task` set and may be answered with a `CreateTaskResult`, and the `tasks/get`, `tasks/result`, `tasks/list`, and `tasks/cancel` methods are registered with `Server.add_request_handler`.
+
+```python
+async def call_tool(
+    ctx: ServerRequestContext, params: CallToolRequestParams
+) -> CallToolResult | CreateTaskResult:
+    if params.task is None:
+        return CallToolResult(content=[TextContent(text=run_now())])
+    return CreateTaskResult(task=await store.submit(params))
+
+
+async def get_task(ctx: ServerRequestContext, params: GetTaskRequestParams) -> GetTaskResult:
+    return await store.status(params.task_id)
+
+
+server = Server("example", on_call_tool=call_tool)
+server.add_request_handler("tasks/get", GetTaskRequestParams, get_task)
+```
+
+Two things to know about handlers registered this way. They serve every negotiated version, so a server that also answers 2026-era clients should check `ctx.protocol_version` and reject anything outside 2025-11-25; the method names collide with the 2026 tasks extension but the payloads are not compatible. And their results are not validated against a per-version surface, so raise `MCPError` for the failure cases rather than letting an exception escape: an unhandled one reaches the client as an unmapped error carrying the exception text.
+
+The same era check belongs in `on_call_tool`. Its return type admits a `CreateTaskResult` at every version because the signature has no version to key on, but 2026-07-28 dropped tasks from the core protocol and rejects the shape, turning it into an opaque internal error. Returning one only when `params.task` is set keeps that unreachable for a well-behaved client, since a client that never learned the field never sets it.
+
+`Server.get_capabilities` does not derive a `tasks` capability from the registered handlers, and a spec-compliant client will not augment a request until it sees one, so build the advertisement explicitly:
+
+```python
+capabilities = server.get_capabilities()
+options = InitializationOptions(
+    server_name="example",
+    server_version="0.1.0",
+    capabilities=capabilities.model_copy(
+        update={
+            "tasks": ServerTasksCapability(
+                list=TasksListCapability(),
+                cancel=TasksCancelCapability(),
+                requests=ServerTasksRequestsCapability(tools=TasksToolsCapability(call={})),
+            )
+        }
+    ),
+)
+```
+
+A client sends the augmented request and names the result type through `ClientSession.send_request`, since `call_tool` resolves to the two core result arms:
+
+```python
+result = await client.session.send_request(
+    CallToolRequest(params=CallToolRequestParams(name="render", task=TaskMetadata(ttl=60_000))),
+    TypeAdapter[CallToolResult | CreateTaskResult](CallToolResult | CreateTaskResult),
+)
+```
+
+The 2026-07-28 revision drops Tasks from the core protocol and reintroduces them as an official extension: [SEP-2663](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2663), `io.modelcontextprotocol/tasks`, redesigned around polling (`tasks/get`) instead of a blocking `tasks/result`. It is a different protocol, not a rename, and this SDK does not implement it yet.
 
 ## Transports
 

docs/whats-new.md

@@ -145,7 +145,7 @@ The renames announce themselves. These do not:
 Each of these is a section in the **[Migration Guide](migration.md)**:
 
 * The **WebSocket transport**, both sides, and the `mcp[ws]` extra. It was never part of the MCP specification.
-* The **experimental Tasks** API (`mcp.*.experimental`). 2026-07-28 moves tasks out of the core protocol and into an official extension ([SEP-2663](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2663)), which this SDK does not implement yet.
+* The **experimental Tasks** runtime (`mcp.*.experimental`): the task store, the polling helper, and the automatic `tasks/*` routing. The task types stay, so a server can still answer a task-augmented `tools/call` on a handshake-era connection by bringing its own store; 2026-07-28 moves tasks out of the core protocol into an official extension ([SEP-2663](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2663)), which this SDK does not implement yet.
 * `mcp.types`, `mcp.shared.version`, and `mcp.shared.progress` as import paths.
 * The deprecated `streamablehttp_client` spelling, and the `get_session_id` callback from `streamable_http_client` (which now yields exactly two streams).
 * `McpError`, renamed **`MCPError`** with a direct `(code, message, data)` constructor.

scripts/gen_surface_types.py

@@ -105,6 +105,9 @@
 # Hand-written union aliases the wire-method maps reference by value; the schema
 # has no named definition for "everything tools/call may return", so name it here.
 EPILOGUES: dict[str, str] = {
+    # SEP-1686: a task-augmented tools/call answers with a CreateTaskResult, which the
+    # 2025-11-25 schema says in prose while leaving it out of its own ServerResult union.
+    "2025-11-25": "AnyCallToolResult = CallToolResult | CreateTaskResult\n",
     "2026-07-28": (
         "AnyCallToolResult = CallToolResult | InputRequiredResult\n"
         "AnyGetPromptResult = GetPromptResult | InputRequiredResult\n"
@@ -218,6 +221,58 @@ def patch(match: re.Match[str]) -> str:
     return source
 
 
+def nullable_required_classes(schema: dict[str, Any]) -> frozenset[str]:
+    """`$defs` entries with a required property whose value may be null.
+
+    `exclude_none=True` drops such a field, producing a body that fails its own schema, so
+    these classes take `KeepRequiredNullable` as a second base. Derived rather than listed,
+    so a new one in a future revision is covered by regenerating.
+
+    This reads each `$def`'s own `required` list; a class that inherits the field through
+    composition is covered because codegen renders the composition as a Python base. The
+    authority is `tests/types/test_parity.py`, which applies the same rule to the built
+    models, so anything this misses fails the suite rather than the wire.
+    """
+    return frozenset(
+        name
+        for name, definition in schema.get("$defs", {}).items()
+        for prop in definition.get("required", [])
+        if _admits_null(definition.get("properties", {}).get(prop, {}))
+    )
+
+
+def _admits_null(prop: dict[str, Any]) -> bool:
+    """Whether `prop` permits a null value: declared as such, composed with null, or unconstrained."""
+    declared = prop.get("type", ())
+    types = {declared} if isinstance(declared, str) else set(declared)
+    if "null" in types:
+        return True
+    # `anyOf: [{$ref: ...}, {type: null}]` is how a nullable reference renders.
+    if any(_admits_null(arm) for arm in (*prop.get("anyOf", ()), *prop.get("oneOf", ()))):
+        return True
+    # No type and no composition keyword at all means any JSON value, null included.
+    return not types and not any(key in prop for key in ("anyOf", "oneOf", "allOf", "$ref", "enum", "const"))
+
+
+def keep_required_nullable(source: str, classes: frozenset[str]) -> str:
+    """Give each of `classes` `KeepRequiredNullable` as a second base."""
+    for name in sorted(classes):
+        source, count = re.subn(
+            rf"^class {name}\(WireModel\):$",
+            f"class {name}(WireModel, KeepRequiredNullable):",
+            source,
+            flags=re.MULTILINE,
+        )
+        if count != 1:
+            raise SystemExit(f"expected one `class {name}(WireModel)` to patch, found {count}")
+    if classes:
+        source = source.replace(
+            "from mcp_types._wire_base import WireModel",
+            "from mcp_types._wire_base import KeepRequiredNullable, WireModel",
+        )
+    return source
+
+
 def build(entry: dict[str, str]) -> str:
     """Generate, post-process, and format one version's surface module text."""
     version = entry["protocol_version"]
@@ -242,6 +297,7 @@ def build(entry: dict[str, str]) -> str:
     # strict mkdocs link validation.
     source = source.replace("](/", "](https://modelcontextprotocol.io/")
     source = allow_open_class_extras(source, OPEN_CLASSES[version])
+    source = keep_required_nullable(source, nullable_required_classes(schema))
     if epilogue := EPILOGUES.get(version, ""):
         # Insert before the trailing model_rebuild() block: pyright's evaluation
         # order for the recursive RootModel block is sensitive to placement.

src/mcp-types/mcp_types/_types.py

@@ -21,6 +21,7 @@
 from pydantic.alias_generators import to_camel
 from typing_extensions import NotRequired, Self, TypedDict
 
+from mcp_types._wire_base import KeepRequiredNullable
 from mcp_types.jsonrpc import RequestId
 
 DEFAULT_NEGOTIATED_VERSION: Final[str] = "2025-03-26"
@@ -636,7 +637,7 @@ class RelatedTaskMetadata(MCPModel):
 """The status of a task (2025-11-25 only)."""
 
 
-class Task(MCPModel):
+class Task(MCPModel, KeepRequiredNullable):
     """Data associated with a task (2025-11-25 only)."""
 
     task_id: str
@@ -1526,7 +1527,7 @@ class SetLevelRequest(Request[SetLevelRequestParams, Literal["logging/setLevel"]
     params: SetLevelRequestParams
 
 
-class LoggingMessageNotificationParams(NotificationParams):
+class LoggingMessageNotificationParams(NotificationParams, KeepRequiredNullable):
     level: LoggingLevel
     """The severity of this log message."""
     logger: str | None = None

src/mcp-types/mcp_types/_wire_base.py

@@ -1,9 +1,81 @@
-"""Shared pydantic base for the generated `mcp_types.v*` wire-shape packages."""
+"""Shared pydantic bases for the generated `mcp_types.v*` packages and the monolith."""
 
-from pydantic import BaseModel, ConfigDict
+from typing import Any, ClassVar, Final, get_args
+
+from pydantic import BaseModel, ConfigDict, SerializationInfo, SerializerFunctionWrapHandler, model_serializer
+
+_UNSET: Final[object] = object()
+"""Tells a field explicitly set to `None` apart from one that was never set."""
 
 
 class WireModel(BaseModel):
     """Base for generated wire models: enables `populate_by_name`; subclasses set `extra` themselves."""
 
     model_config = ConfigDict(populate_by_name=True)
+
+
+class KeepRequiredNullable(BaseModel):
+    """Base for models carrying a required nullable field, e.g. `Task.ttl` (`number | null`).
+
+    Every dump path passes `exclude_none=True` to omit unset optionals, but that cannot tell an
+    unset optional from a required field whose value is legitimately null, so it drops both and
+    leaves a body that fails the schema it was just validated against. This puts the required
+    ones back, and only those: a field the caller filtered out with `include`/`exclude`, or one
+    that was never set at all, stays absent.
+
+    Mixed in only where it is needed, since a wrap serializer costs per dump:
+    `scripts/gen_surface_types.py` derives the surface classes from the schema and the monolith
+    counterparts take it by hand, with `tests/types/test_parity.py` checking the set is complete.
+    """
+
+    _nullable_required_fields: ClassVar[tuple[tuple[str, str], ...] | None] = None
+    """`(attribute, wire alias)` per required nullable field; resolved on first dump, then cached."""
+
+    @classmethod
+    def _resolve_nullable_required(cls) -> tuple[tuple[str, str], ...]:
+        """Find the fields `exclude_none` must not drop, once per concrete class.
+
+        Deferred to first use rather than `__pydantic_init_subclass__`: the generated modules
+        use `from __future__ import annotations` and finish with `model_rebuild()`, so a forward
+        reference is still a string at class-creation time and would resolve to nothing. Each
+        class resolves its own set, since subclasses add fields (`GetTaskResult` is `Result`
+        plus `Task`).
+        """
+        resolved = tuple(
+            (name, field.serialization_alias or field.alias or name)
+            for name, field in cls.model_fields.items()
+            if field.is_required() and _admits_none(field.annotation)
+        )
+        cls._nullable_required_fields = resolved
+        return resolved
+
+    @model_serializer(mode="wrap")
+    def _keep_required_nullable(self, handler: SerializerFunctionWrapHandler, info: SerializationInfo):
+        # The return is deliberately unannotated: pydantic builds the serialization JSON schema
+        # from this signature, and any annotation collapses the whole model's schema to an
+        # opaque object for anyone generating schemas over these types.
+        data = handler(self)
+        if not info.exclude_none:
+            return data
+        # `__dict__`, not attribute lookup: a subclass must resolve its own set rather than
+        # inherit whichever ancestor happened to be dumped first.
+        cls = type(self)
+        fields = cls.__dict__.get("_nullable_required_fields")
+        if fields is None:
+            fields = cls._resolve_nullable_required()
+        for name, alias in fields:
+            if self.__dict__.get(name, _UNSET) is not None:
+                continue
+            if (info.include is not None and name not in info.include) or (
+                info.exclude is not None and name in info.exclude
+            ):
+                continue  # the caller filtered this field out; exclude_none is not why it is gone
+            data.setdefault(alias if info.by_alias else name, None)
+        return data
+
+
+def _admits_none(annotation: Any) -> bool:
+    """Whether a field's annotation accepts `None`, including a bare `Any`."""
+    if annotation is Any or annotation is None:
+        return True
+    return type(None) in get_args(annotation)

src/mcp-types/mcp_types/jsonrpc.py

@@ -6,6 +6,8 @@
 
 from pydantic import BaseModel, Field, TypeAdapter
 
+from mcp_types._wire_base import KeepRequiredNullable
+
 RequestId = Annotated[int, Field(strict=True)] | str
 """The ID of a JSON-RPC request."""
 
@@ -106,7 +108,7 @@ class ErrorData(BaseModel):
     """
 
 
-class JSONRPCError(BaseModel):
+class JSONRPCError(KeepRequiredNullable):
     """A response to a request that indicates an error occurred."""
 
     jsonrpc: Literal["2.0"]