Adapt the Tasks extension to main after rebasing onto the released 2026-07-28 line

The 15-commit branch rebased onto latest main with four textual conflicts
(extension.py + mcpserver/server.py, the everything-server, client/__init__.py,
whats-new.md), all resolved to main's structure plus the branch's additions.
This commit carries the semantic adaptations that the merge could not surface:

- Gate task augmentation on the declared-capabilities fact, not clientInfo.
  Main made clientInfo optional on the 2026-07-28 wire (spec #3002) and split
  `session.client_capabilities` from `session.client_params`, so a conformant
  client can declare the extension while `client_params` is None. The
  interceptor's `_client_declared_tasks` now reads `client_capabilities`,
  matching main's rewritten `require_client_extension` (whose main body the
  relocated function carries). A pair-only declaring envelope is augmented.

- Interceptors now run at the handler layer (`compose_tool_call_handler`), so
  `call_next` returns the wrapped handler's domain result rather than a
  serialized dict, and every modern-era result envelope carries the
  `serverInfo` `_meta` identity stamp. The stored/inlined tool result stays
  the un-enveloped payload. Reword `_wire_payload` and the error-fold comment
  accordingly, and have the tests assert-and-strip the envelope stamp through
  strict helpers mirroring tests/_stamp.py instead of hard-coding it into
  every snapshot. A short-circuited `input_required` interim is now sieved to
  the core shape like any handler result, so its fixture is core-shaped.

- Declare `name_param = "taskId"` on GetTaskRequest/CancelTaskRequest/
  UpdateTaskRequest: main added `Request.name_param` as the per-request key a
  client mirrors into the `Mcp-Name` header, built expressly for the tasks
  verbs (its placeholder test models `tasks/get`). The server-side
  NAME_BEARING_METHODS rows remain the source of the spec-mandated validation.

- Follow main's spelling and toolchain moves: httpx -> httpx2 in the tasks
  server tests, `mcp.types` (not `mcp_types`) in docs/example imports with the
  matching `hl_lines` shift, and the GitHub form for SEP-2663 links.

- Refresh prose that the merge left stale: the migration guide's "Detached
  work" note now points at the extension for the fetch-later half, and the
  tasks story's docstring states the fixed-contract invariant rather than
  claiming identity with a task-less server's stamped result.

Author: maxisbey

docs/advanced/tasks.md

@@ -3,7 +3,7 @@
 A **task** is a `tools/call` answered by reference: instead of the `CallToolResult`,
 the server returns a `CreateTaskResult` carrying a task id, and the client fetches
 the outcome with `tasks/get`. That is
-[SEP-2663](https://modelcontextprotocol.io/seps/2663-tasks-extension.md), and the SDK
+[SEP-2663](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2663), and the SDK
 ships it as the built-in `Tasks` extension (`io.modelcontextprotocol/tasks`).
 If [Extensions](extensions.md) are new to you, skim that page first. One minute,
 then come back.
@@ -44,7 +44,7 @@ Augmentation is the server's call, per request: the client's declaration is
 permission, not a trigger. `Tasks()` augments every call from a declaring client;
 pass `augment=` to be choosier:
 
-```python title="server.py" hl_lines="9-10 13"
+```python title="server.py" hl_lines="8-9 12"
 --8<-- "docs_src/tasks/tutorial002.py"
 ```
 

docs/migration.md

@@ -2010,7 +2010,7 @@ async def elicitation_callback(
 
 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`.
 
-Tasks have since returned as the built-in `Tasks` extension ([SEP-2663](https://modelcontextprotocol.io/seps/2663-tasks-extension.md)), with a different wire shape than the experimental SEP-1686 surface. See [Extensions](advanced/extensions.md) and [Tasks](advanced/tasks.md) for the new design.
+Tasks have since returned as the built-in `Tasks` extension ([SEP-2663](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2663)), with a different wire shape than the experimental SEP-1686 surface. See [Extensions](advanced/extensions.md) and [Tasks](advanced/tasks.md) for the new design.
 
 There is no drop-in replacement for the tasks runtime (`server.experimental.enable_tasks()`, `ctx.experimental.run_task()`, `ServerTaskContext`, and the client's `session.experimental.call_tool_as_task()` / `poll_task()` / `get_task_result()`); the port depends on what the code used tasks for.
 
@@ -2052,7 +2052,7 @@ result = await client.call_tool("long_running_task", {}, progress_callback=on_pr
 
 **Gathering user input mid-work** (`task.elicit()`, `task.create_message()`). Don't port these to inline `ctx.elicit()` / `ctx.session.create_message()` calls: those are server-initiated requests, refused with `NoBackChannelError` on 2026-07-28 connections (the default for an in-process `Client(server)`). Use the resolver dependencies (`Elicit`, `Sample`) or return an `InputRequiredResult` — both work on every protocol version, and `Client.call_tool()` retries the `InputRequiredResult` rounds automatically; see [Multi-round-trip requests](handlers/multi-round-trip.md) and [Server-initiated sampling, elicitation, and roots raise `NoBackChannelError`](#server-initiated-sampling-elicitation-and-roots-raise-nobackchannelerror). The client's existing `elicitation_callback` / `sampling_callback` serve both eras.
 
-**Detached work** (create the task now, fetch its result on a later connection or after a client restart) has no v2 equivalent until the SEP-2663 extension is implemented.
+**Detached work** (create the task now, fetch its result on a later connection or after a client restart): the built-in [Tasks](advanced/tasks.md) extension covers the fetch-later half for clients that declare `io.modelcontextprotocol/tasks` on a 2026-07-28 connection — an augmented `tools/call` returns a `CreateTaskResult`, and a later declaring connection holding the task id polls `tasks/get` (or calls `wait_task(session, task_id)` from `mcp.client.tasks`) to collect the outcome, which is retained per the task's `ttlMs` (with no TTL configured, for the store's lifetime). Two caveats: the default store is in-memory and per-process, so surviving a *server* restart or spanning workers needs a custom `Tasks(store=...)`; and the tool still runs inline inside the original `tools/call`, so there is no create-now, compute-in-the-background equivalent of the v1 task runtime yet.
 
 Also drop `execution=ToolExecution(taskSupport=types.TASK_REQUIRED)` from tool definitions: the `TASK_REQUIRED` / `TASK_OPTIONAL` / `TASK_FORBIDDEN` constants are gone from `mcp.types` (`ToolExecution.task_support` takes the plain `"required"` / `"optional"` / `"forbidden"` literal), and no v2 client or server reads the field.
 

docs_src/tasks/tutorial002.py

@@ -1,7 +1,6 @@
-from mcp_types import CallToolRequestParams
-
 from mcp.server.mcpserver import MCPServer
 from mcp.server.tasks import Tasks
+from mcp.types import CallToolRequestParams
 
 SLOW_TOOLS = {"transcode"}
 

examples/stories/tasks/README.md

@@ -59,7 +59,7 @@ table).
 
 ## Spec
 
-[SEP-2663 — Tasks extension](https://modelcontextprotocol.io/seps/2663-tasks-extension.md)
+[SEP-2663 — Tasks extension](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2663)
 · [SEP-2133 — extensions capability](https://github.com/modelcontextprotocol/modelcontextprotocol/issues/2133)
 
 ## See also

examples/stories/tasks/client.py

@@ -4,14 +4,14 @@
 `TasksExtension()` into `Client(extensions=...)`),
 so the server is free to answer `tools/call` with a `CreateTaskResult`. SEP-2663
 advises clients to keep a fixed public contract and drive the polling internally —
-`Client.call_tool` does exactly that, so the modern path is the same typed call a
-task-less server would get. A compact manual leg then shows the raw wire flow:
-`session.call_tool(allow_claimed=True)` for the typed `CreateTaskResult`, and the
-typed `mcp.client.tasks` functions (`get_task`, `wait_task`) to drive `tasks/get`.
+`Client.call_tool` does exactly that, so the caller keeps one fixed
+`CallToolResult` contract whether or not the server augments. A compact manual
+leg then shows the raw wire flow: `session.call_tool(allow_claimed=True)` for the
+typed `CreateTaskResult`, and the typed `mcp.client.tasks` functions (`get_task`,
+`wait_task`) to drive `tasks/get`.
 """
 
-import mcp_types as types
-
+import mcp.types as types
 from mcp.client import Client, TasksExtension
 from mcp.client.tasks import get_task, wait_task
 from mcp.shared.tasks import EXTENSION_ID, CreateTaskResult
@@ -28,8 +28,10 @@ async def main(target: Target, *, mode: str = "auto") -> None:
         result = await client.call_tool("render_report", {"title": "Q3", "sections": 2})
         assert isinstance(result.content[0], types.TextContent), result
         assert result.content[0].text.startswith("# Q3"), result
-        # No 2025-style related-task _meta either; the task plumbing never leaks
-        # into the surfaced result.
+        # The surfaced value is the tool's own CallToolResult - the payload the
+        # task recorded, or on the legacy wire the plain result. No task plumbing
+        # leaks in: no 2025-style related-task _meta, and no envelope-level identity
+        # stamp either, since it is the tool's result and not a response envelope.
         assert result.meta is None, result
 
         if client.server_capabilities.extensions is None:

src/mcp/server/mcpserver/server.py

@@ -1312,4 +1312,3 @@ async def gated(ctx: ServerRequestContext[Any, Any], params: Any) -> HandlerResu
         return await method.handler(ctx, params)
 
     return gated
-

src/mcp/server/tasks.py

@@ -4,7 +4,7 @@
 `CallToolResult`, the server immediately returns a `CreateTaskResult` carrying a
 task id, and the client polls `tasks/get` for status and the eventual result.
 
-SEP-2663 (https://modelcontextprotocol.io/seps/2663-tasks-extension.md) is an
+SEP-2663 (https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2663) is an
 opt-in extension, wire-incompatible with the 2025-11-25 in-core Tasks design that
 still ships (types-only) in `mcp_types`. The SEP-2663-shaped wire models live in
 `mcp.shared.tasks` (re-exported here); this module is the server runtime.
@@ -50,7 +50,9 @@
 `notifications/tasks` over `subscriptions/listen` are deferred follow-ups, each
 needing deeper SDK plumbing. (SEP-2663's `Mcp-Name: <taskId>` routing header --
 the SEP-2243 header family -- is already handled by the shared header table in
-`mcp.shared.inbound`.)
+`mcp.shared.inbound`; the `tasks/*` request types in `mcp.shared.tasks` also
+declare `name_param`, the per-request params key a client mirrors into that
+header.)
 
 Task ids are unguessable bearer capabilities: any caller presenting a valid id
 may poll the task. That is deliberate -- the modern wire has no sessions, and a
@@ -245,8 +247,10 @@ async def intercept_tool_call(
         try:
             result = await call_next(ctx)
             if isinstance(result, ErrorData):
-                # A nested extension returned the error instead of raising (the
-                # runner's middleware error channel); fold it into the same arm.
+                # A handler or nested extension returned the error instead of
+                # raising (the runner folds handler-returned `ErrorData` into an
+                # `MCPError` only after this composed handler returns), so fold
+                # it into the same arm here.
                 raise MCPError.from_error_data(result)
         except MCPError as exc:
             # SEP-2663: a JSON-RPC error during execution is a `failed` task,
@@ -339,11 +343,12 @@ async def _require(self, task_id: str) -> TaskRecord:
 
 
 def _wire_payload(result: HandlerResult) -> dict[str, Any]:
-    """Normalize a `call_next` outcome to the wire dict the chain would emit.
+    """Normalize a `call_next` outcome to the wire dict it will be serialized as.
 
-    The stock composition hands the interceptor the already-serialized dict; an
-    extension or middleware nested inside this one may short-circuit with a
-    model (dumped the way the runner would) or `None` (an empty result).
+    The stock composition hands the interceptor the wrapped handler's domain
+    result (a `CallToolResult`/`InputRequiredResult` model); an extension nested
+    inside this one may instead short-circuit with a wire-shaped dict or `None`
+    (an empty result). Models are dumped the way the runner would.
     """
     if isinstance(result, BaseModel):
         return result.model_dump(by_alias=True, mode="json", exclude_none=True)
@@ -357,6 +362,9 @@ def _client_declared_tasks(ctx: ServerRequestContext[Any, Any]) -> bool:
     # capabilities happen to include the identifier.
     if ctx.protocol_version not in MODERN_PROTOCOL_VERSIONS:
         return False
-    client_params = ctx.session.client_params
-    declared = client_params.capabilities.extensions if client_params else None
+    # Read the declared-capabilities fact, not `client_params`: on 2026-07-28 the
+    # request envelope declares capabilities while `clientInfo` stays optional,
+    # so a conformant client can be declaring with no `client_params` at all.
+    capabilities = ctx.session.client_capabilities
+    declared = capabilities.extensions if capabilities else None
     return bool(declared and EXTENSION_ID in declared)

src/mcp/shared/tasks.py

@@ -1,6 +1,6 @@
 """Wire models for the Tasks extension (`io.modelcontextprotocol/tasks`, SEP-2663).
 
-SEP-2663 (https://modelcontextprotocol.io/seps/2663-tasks-extension.md) is an
+SEP-2663 (https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2663) is an
 opt-in extension, wire-incompatible with the 2025-11-25 in-core Tasks design that
 still ships (types-only) in `mcp_types`. This module therefore defines its own
 SEP-2663-shaped models rather than reusing `mcp_types.{Task, CreateTaskResult, ...}`.
@@ -116,20 +116,23 @@ class GetTaskRequest(Request[GetTaskRequestParams, Literal["tasks/get"]]):
 
     method: Literal["tasks/get"] = "tasks/get"
     params: GetTaskRequestParams
+    name_param = "taskId"
 
 
 class CancelTaskRequest(Request[CancelTaskRequestParams, Literal["tasks/cancel"]]):
     """SEP-2663 `tasks/cancel` request, typed for client-side `send_request`."""
 
     method: Literal["tasks/cancel"] = "tasks/cancel"
     params: CancelTaskRequestParams
+    name_param = "taskId"
 
 
 class UpdateTaskRequest(Request[UpdateTaskRequestParams, Literal["tasks/update"]]):
     """SEP-2663 `tasks/update` request, typed for client-side `send_request`."""
 
     method: Literal["tasks/update"] = "tasks/update"
     params: UpdateTaskRequestParams
+    name_param = "taskId"
 
 
 class GetTaskResult(Task):

tests/docs_src/test_tasks.py

@@ -10,6 +10,7 @@
 from mcp.server.mcpserver import MCPServer
 from mcp.server.tasks import EXTENSION_ID, CreateTaskResult, Tasks
 from mcp.shared.tasks import GetTaskResult
+from tests._stamp import unstamped
 
 # See test_index.py for why this is a per-module mark and not a conftest hook.
 pytestmark = [pytest.mark.anyio, pytest.mark.filterwarnings("error::mcp.MCPDeprecationWarning")]
@@ -48,9 +49,12 @@ async def test_the_bakery_client_program_runs_as_shown(capsys: pytest.CaptureFix
 
 async def test_a_non_declaring_client_is_never_augmented() -> None:
     """tutorial001 + the degradation paragraph: a modern client that did not declare
-    the extension gets the plain `CallToolResult`, always."""
+    the extension gets the plain `CallToolResult`, always -- no task metadata. The
+    only `_meta` present is the era's `serverInfo` identity stamp, which `unstamped`
+    asserts and pops, so `meta is None` proves nothing else rode along."""
     async with Client(tutorial001.mcp) as client:
         result = await client.call_tool("bake", {"flavor": "plain"})
+    result = unstamped(result)
     assert result.content == [TextContent(type="text", text="One plain cake, ready.")]
     assert result.meta is None