Update the tasks story and docs for the reworked extension

The stdio leg now asserts graceful degradation (a legacy connection gets
a plain CallToolResult, never a task) instead of returning silently; the
stories index lists tasks as a current feature story; the migration note
reflects the -32021 capability error, the tasks/update acknowledgement,
and the pluggable store, and drops the taskSupport item (SEP-2663
defines no per-tool execution flag).

Author: maxisbey

docs/migration.md

@@ -433,12 +433,17 @@ Two reference extensions ship in their own modules:
 - `mcp.server.tasks.Tasks` (`io.modelcontextprotocol/tasks`, SEP-2663) defers a
   `tools/call` as a task: for a client that declared the extension on a modern
   connection, the server may return a `CreateTaskResult` (`resultType: "task"`)
-  instead of the `CallToolResult`, and the client polls `tasks/get` /
-  `tasks/cancel`. The server decides augmentation (the legacy `params.task` field
-  is ignored); a `tasks/*` call from a non-declaring client is rejected with
-  `-32003`. This is the conformant core; `tasks/update` + the MRTR input loop,
-  `ToolExecution.taskSupport` gating, `notifications/tasks`, and task routing
-  headers are deferred.
+  instead of the `CallToolResult`, and the client fetches the result via
+  `tasks/get` (`tasks/update` and `tasks/cancel` are empty acknowledgements).
+  The server decides augmentation (the legacy `params.task` field is ignored),
+  passes multi round-trip `input_required` interims through un-augmented, and
+  keeps completed tasks in a pluggable `TaskStore` (`Tasks(store=...)`,
+  in-memory default) that enforces `default_ttl_ms`. A `tasks/*` call from a
+  non-declaring modern client is rejected with `-32021` (missing required
+  client capability); legacy calls get `METHOD_NOT_FOUND`. This is the core
+  SEP-2663 surface; background execution (`working` tasks), the in-task
+  `input_required` loop over `tasks/update`, `notifications/tasks`, and task
+  routing headers are deferred.
 
 A `MethodBinding` may set `protocol_versions` to scope an extension method to
 specific wire versions; a request at any other version is `METHOD_NOT_FOUND`. An

examples/stories/README.md

@@ -132,6 +132,7 @@ opens with a banner saying what replaces it.
 | [`sampling`](sampling/) | server asks the client's LLM mid-tool (push request) | deprecated |
 | [`stickynotes`](stickynotes/) | capstone: tools mutate state → resources + `list_changed` + elicit guard | current |
 | [`custom_methods`](custom_methods/) | vendor-prefixed JSON-RPC via `add_request_handler` / `send_request` | current |
+| [`tasks`](tasks/) | `io.modelcontextprotocol/tasks` extension: server-decided `CreateTaskResult`, `tasks/get` | current |
 | [`schema_validators`](schema_validators/) | tool input schema from pydantic / TypedDict / dataclass / dict | current |
 | [`middleware`](middleware/) | server-side request/response middleware | current |
 | [`parallel_calls`](parallel_calls/) | two clients rendezvous in one tool; per-call progress attribution | current |
@@ -154,7 +155,6 @@ opens with a banner saying what replaces it.
 | [`caching`](caching/) | `CacheableResult` ttl/scope hints; client honouring | not yet implemented |
 | [`mrtr`](mrtr/) | `InputRequiredResult` round-trip with `requestState` HMAC | not yet implemented — [#2898](https://github.com/modelcontextprotocol/python-sdk/issues/2898) |
 | [`subscriptions`](subscriptions/) | `subscriptions/listen`, `ServerEventBus`, `Client.listen()` | not yet implemented — [#2901](https://github.com/modelcontextprotocol/python-sdk/issues/2901) |
-| [`tasks`](tasks/) | `io.modelcontextprotocol/tasks` extension | not yet implemented |
 | [`apps`](apps/) | MCP Apps: `ui://` resource + `_meta.ui` | not yet implemented — [#2896](https://github.com/modelcontextprotocol/python-sdk/issues/2896) |
 | [`skills`](skills/) | SEP-2640 skills extension | not yet implemented — [#2896](https://github.com/modelcontextprotocol/python-sdk/issues/2896) |
 | [`events`](events/) | `io.modelcontextprotocol/events` extension | not yet implemented |

examples/stories/tasks/README.md

@@ -2,40 +2,46 @@
 
 Task-augmented execution (SEP-2663). A client declares the
 `io.modelcontextprotocol/tasks` extension; the server may then answer a
-`tools/call` with a `CreateTaskResult` (carrying a task id) instead of blocking,
-and the client polls `tasks/get` for status and the eventual result.
+`tools/call` with a `CreateTaskResult` (carrying a task id) instead of the
+`CallToolResult`, and the client fetches the result via `tasks/get`.
 
 ## Run it
 
 ```bash
-# stdio (default — the client spawns the server as a subprocess)
+# stdio (default) — today's stdio negotiates the legacy wire, which cannot carry
+# the extension capability, so this leg demonstrates graceful degradation: the
+# same tools/call returns a plain CallToolResult, never a task.
 uv run python -m stories.tasks.client
 
-# HTTP — the client self-hosts the server on a free port, runs, then tears it down
+# HTTP — the modern wire negotiates the extension; the server defers the call as
+# a task and the client reads the result back via tasks/get
 uv run python -m stories.tasks.client --http
 ```
 
 ## What to look at
 
 - `server.py` `MCPServer("tasks-example", extensions=[Tasks(default_ttl_ms=...)])` —
   opt in at construction. The extension advertises `io.modelcontextprotocol/tasks`
-  and serves `tasks/get` and `tasks/cancel`.
+  and serves `tasks/get`, `tasks/update`, and `tasks/cancel` on the modern wire
+  (legacy calls are `METHOD_NOT_FOUND`; the extension is not defined there).
 - `mcp.server.tasks.Tasks.intercept_tool_call` — the server DECIDES augmentation;
   the legacy `params.task` field is ignored. It augments only for a client that
   declared the extension on the request, returning a flat `CreateTaskResult`
   (`resultType: "task"`).
 - `client.py` `Client(target, extensions={EXTENSION_ID: {}})` — declaring the
   extension is what lets the server defer; `main` then reads the `CreateTaskResult`
-  and polls `tasks/get`, whose completed `DetailedTask` inlines the original
+  and fetches `tasks/get`, whose completed envelope inlines the original
   `CallToolResult`.
 
 ## Scope
 
-This is the SEP-2663 conformant *core*. The tool runs to completion inline (so a
-task is observed as `completed` immediately), and the store is in-memory. Deferred
-to follow-ups, each needing deeper SDK plumbing: `tasks/update` + the MRTR
-`input_required` loop, `ToolExecution.taskSupport` gating with the `-32021`
-required-task error, `notifications/tasks`, and SEP-2243 task routing headers.
+This is the core SEP-2663 surface. The tool runs to completion inline, so a task
+is recorded directly as `completed` (the SEP allows any initial status), and
+completed tasks live in a pluggable `TaskStore` (`Tasks(store=...)`, in-memory
+default) that enforces `default_ttl_ms`. Deferred to follow-ups, each needing
+deeper SDK plumbing: background execution (returning `working` tasks), the
+in-task `input_required`/`inputResponses` loop over `tasks/update`,
+`notifications/tasks`, and SEP-2243 task routing headers.
 
 ## Spec
 

examples/stories/tasks/client.py

@@ -1,4 +1,4 @@
-"""Declare the tasks extension, let the server defer a tool call, then poll tasks/get.
+"""Declare the tasks extension, let the server defer a tool call, then fetch the result via tasks/get.
 
 The client declares `io.modelcontextprotocol/tasks` (via `Client(extensions=...)`),
 so the server is free to answer `tools/call` with a `CreateTaskResult`. `Client`
@@ -32,8 +32,14 @@ async def main(target: Target, *, mode: str = "auto") -> None:
     async with Client(target, mode=mode, extensions={EXTENSION_ID: {}}) as client:
         # The extension is a modern-only capability negotiated over server/discover.
         # A legacy connection (today's stdio) cannot carry it, and the server then
-        # must not augment, so the task flow only runs once it is negotiated.
+        # must not augment: the same tools/call degrades to a plain CallToolResult.
         if client.server_capabilities.extensions is 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; SEP-2663 augmentation would
+            # have replaced the whole result, failing CallToolResult parsing above.
+            assert result.meta is None, result
             return
         assert client.server_capabilities.extensions == {EXTENSION_ID: {}}
 

examples/stories/tasks/server.py

@@ -1,10 +1,10 @@
-"""Tasks (SEP-2663): the server defers a tool call as a task the client polls.
+"""Tasks (SEP-2663): the server defers a tool call as a task the client fetches.
 
 `Tasks` is an opt-in `Extension`. The server decides, per request, to return a
 `CreateTaskResult` instead of a `CallToolResult` for a client that declared the
-`io.modelcontextprotocol/tasks` extension; the client then polls `tasks/get` for
-status and the eventual result. `render_report` is the kind of slower, multi-step
-tool a caller would rather run as a task than block on.
+`io.modelcontextprotocol/tasks` extension; the client then fetches the result via
+`tasks/get`. `render_report` is the kind of slower, multi-step tool a caller
+would rather run as a task than block on.
 """
 
 from mcp.server.mcpserver import MCPServer