[Schema][Client][Server] Add the Tasks extension (SEP-2663)

`io.modelcontextprotocol/tasks`: `Task` and `TaskStatus`, `ResultType::Task`,
the `CreateTaskResult` / `TaskResult` wire shapes, the `tasks/get` /
`tasks/update` / `tasks/cancel` handlers behind `TasksExtension`,
`TaskStoreInterface` with in-memory and PSR-16 stores,
`RequestContext::createTask()` / `supportsTasks()`, and the -32021 refusal for
a task handed to a client that did not declare the extension.

On the client, `enableExtension(new TasksExtension())` declares it, the call
methods return a `CreateTaskResult` when the server answered with a task, and
`getTask()` / `updateTask()` / `cancelTask()` drive it. Covered end to end by
an integration test against a stdio fixture server.

Extensions that add methods implement `MethodProvidingExtensionInterface`;
`Builder::enableExtension()` registers their messages and handlers. Extension
settings serialize as `{}` rather than `[]` when empty.

Author: chr-hertel

CHANGELOG.md

@@ -5,6 +5,8 @@ All notable changes to `mcp/sdk` will be documented in this file.
 0.8.0
 -----
 
+* Add the Tasks extension (SEP-2663, `io.modelcontextprotocol/tasks`): a server can hand back a durable handle instead of holding a connection open. `Mcp\Schema\Task` and `TaskStatus`, `ResultType::Task`, the `CreateTaskResult` / `TaskResult` wire shapes (flat — the result *is* the task), the `tasks/get` / `tasks/update` / `tasks/cancel` surface, and `TaskStoreInterface` with `InMemoryTaskStore` and `Psr16TaskStore` implementations — the latter being what PHP-FPM needs, since the worker that creates a task is not the one polled for it. Enable with `Builder::enableExtension(new TasksExtension($store))`; handlers create a task through `RequestContext::createTask()` after checking `supportsTasks()`, and a task created for a client that did not declare the extension is refused with `-32021` rather than sent. Advancing a task is the application's job. On the client, `Client\Builder::enableExtension(new TasksExtension())` declares it, `Client::callTool()` / `getPrompt()` / `readResource()` now return a `CreateTaskResult` when the server answered with a task (a widening of their return types), and `Client::getTask()` / `updateTask()` / `cancelTask()` drive it. Extensions that add methods of their own implement the new `MethodProvidingExtensionInterface`, and `Builder::enableExtension()` registers their messages and handlers.
+* Serialize an extension's settings as `{}` rather than `[]` when it has none, in both `ServerCapabilities` and `ClientCapabilities`; an extension declaring support with no settings was advertised as an empty JSON array, which the schema does not allow.
 * Add `ClientGateway::supportsExtension()` to check whether the client negotiated a protocol extension (e.g. `McpApps::EXTENSION_ID`) before offering UI-linked tools, plus `Client\Builder::enableExtension()` and `ClientCapabilities::withExtensions()` so hosts advertise extensions the same way servers do. [BC Break] `ServerExtensionInterface` is replaced by the side-agnostic `Mcp\Schema\Extension\ExtensionInterface`.
 * Deprecate the Roots, Sampling and Logging features per SEP-2577 (protocol revision `2026-07-28`, earliest removal `2027-07-28`): the schema, client and server classes that make them up are marked `@deprecated` with the suggested migration (tool arguments or resource URIs instead of roots; an LLM provider's API instead of sampling; stderr or OpenTelemetry instead of logging), and exercising them — `ClientGateway::log()` / `sample()` / `listRoots()`, or registering a client-side `SamplingRequestHandler`, `ListRootsRequestHandler` or `LoggingNotificationHandler` — triggers a silenced `E_USER_DEPRECATED` via `symfony/deprecation-contracts`. Everything remains fully functional until removal.
 * Always emit `{}` for empty tool schemas: `Tool` recursively normalizes every empty sub-schema — `properties`, `items`, `additionalProperties`, `$defs`, combinators and the other draft-07 to 2020-12 schema keywords — in the constructor, for both `inputSchema` and `outputSchema`, so an object position is never serialized as `[]`.

docs/extensions.md

@@ -45,6 +45,113 @@ public function getWeather(string $city, RequestContext $context): string
 }
 ```
 
+An extension that adds RPC methods of its own implements
+`MethodProvidingExtensionInterface` on top: its message classes are registered
+with the `MessageFactory` and its request handlers with the server, so enabling
+it is all it takes for those methods to exist.
+
+## Tasks (`io.modelcontextprotocol/tasks`)
+
+The [Tasks extension][ext-tasks] (SEP-2663) lets a server hand back a durable
+handle instead of holding a connection open for a long-running request. The
+client polls `tasks/get` until the task settles, answers anything it asks for
+through `tasks/update`, and may `tasks/cancel` it.
+
+```php
+use Mcp\Server;
+use Mcp\Server\Task\InMemoryTaskStore;
+use Mcp\Server\Task\Psr16TaskStore;
+use Mcp\Server\Task\TasksExtension;
+
+$server = Server::builder()
+    ->enableExtension(new TasksExtension(new InMemoryTaskStore()))
+    ->build();
+```
+
+`InMemoryTaskStore` is right for stdio and any single-process runtime and drops
+its oldest task past a configurable limit (1000 by default). Under PHP-FPM the
+worker that creates a task is not the one polled for it, so use
+`Psr16TaskStore` over a shared cache there — a filesystem adapter is enough.
+
+Creating a task is the *server's* decision, made per request by returning a
+`CreateTaskResult` from any tool, prompt or resource handler:
+
+```php
+use Mcp\Schema\Result\CreateTaskResult;
+use Mcp\Server\RequestContext;
+
+static function (RequestContext $context) use ($queue): CreateTaskResult|string {
+    if (!$context->supportsTasks()) {
+        return runSynchronously();          // the client cannot poll, so answer now
+    }
+
+    $created = $context->createTask(ttlMs: 600_000, pollIntervalMs: 1000);
+    $queue->push($created->task->taskId);   // a worker calls $store->save() as it progresses
+
+    return $created;
+}
+```
+
+`createTask()` stores the task *before* returning it, so the first `tasks/get`
+cannot arrive before the task exists. A client that did not declare the
+extension during `initialize` is refused a task handle with `-32021`
+(missing required client capability) rather than being left holding a handle it
+cannot redeem — which is the right answer for a handler whose task support is
+*required*, and what `supportsTasks()` lets an optional one avoid.
+
+The SDK owns storage and the `tasks/get` / `tasks/update` / `tasks/cancel`
+surface; **advancing** a task is the application's job. A worker (or a
+handler, through `RequestContext::getTaskStore()` or a `TaskStoreInterface`
+parameter) saves the task with a new status as it goes:
+
+```php
+use Mcp\Schema\Enum\TaskStatus;
+
+$store->save($task->with(TaskStatus::Completed, result: ['content' => [/* ... */]]));
+```
+
+A task that needs the client's input parks itself as `input_required` with
+`inputRequests` (elicitation, sampling or roots requests keyed by name); the
+client answers through `tasks/update`, and a `TaskInputHandlerInterface` passed
+to `TasksExtension` decides what those answers mean for the task.
+
+Status semantics worth getting right: a tool that ran and reported a problem is
+`completed` with `isError` on its result — `failed` is reserved for
+protocol-level errors, and carries the error inlined instead of a result.
+`Task` refuses to be constructed the other way round.
+
+### On the client
+
+A client declares the extension the same way, and then handles whichever
+result shape arrives — `callTool()`, `getPrompt()` and `readResource()` return
+a `CreateTaskResult` when the server chose to answer with a task:
+
+```php
+use Mcp\Client;
+use Mcp\Schema\Result\CallToolResult;
+use Mcp\Schema\Result\CreateTaskResult;
+use Mcp\Server\Task\TasksExtension;
+
+$client = Client::builder()
+    ->enableExtension(new TasksExtension())
+    ->build();
+
+$result = $client->callTool('long_job');
+
+if ($result instanceof CreateTaskResult) {
+    do {
+        usleep(1000 * ($result->task->pollIntervalMs ?? 1000));
+        $task = $client->getTask($result->task->taskId);
+    } while (!$task->status->isTerminal());
+
+    $result = CallToolResult::fromArray($task->result);   // once completed
+}
+```
+
+A task waiting as `input_required` lists its `inputRequests`; answer them with
+`updateTask($taskId, ['<key>' => $answer])`, keyed as the requests were, and
+`cancelTask($taskId)` asks the server to stop.
+
 ## MCP Apps (`io.modelcontextprotocol/ui`)
 
 The [MCP Apps extension][ext-apps] lets servers expose interactive HTML UIs as
@@ -155,3 +262,4 @@ working minimal view is included in
 [`examples/server/mcp-apps/weather-app.html`](../examples/server/mcp-apps/weather-app.html).
 
 [ext-apps]: https://github.com/modelcontextprotocol/ext-apps
+[ext-tasks]: https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2663

docs/index.md

@@ -5,7 +5,7 @@
 - [Client](client.md) — Client SDK for connecting to and communicating with MCP servers.
 - [Transports](transports.md) — STDIO and HTTP transport implementations with guidance on choosing between them.
 - [Server-Client Communication](server-client-communication.md) — Methods for servers to communicate back to clients: sampling, logging, progress, and notifications.
-- [Protocol Extensions](extensions.md) — Opt-in protocol extensions announced during capability negotiation, including MCP Apps (HTML UI resources).
+- [Protocol Extensions](extensions.md) — Opt-in protocol extensions announced during capability negotiation, including Tasks (durable handles for long-running requests) and MCP Apps (HTML UI resources).
 - [Authorization](authorization.md) — OAuth and authorization setup for the HTTP transport.
 - [Events](events.md) — Hooking into the server lifecycle with PSR-14 events.
 - [Examples](examples.md) — Example projects demonstrating attribute-based discovery, dependency injection, HTTP transport, and more.

src/Capability/Registry/ReferenceHandler.php

@@ -16,15 +16,20 @@
 use Mcp\Server\ClientGateway;
 use Mcp\Server\RequestContext;
 use Mcp\Server\Session\SessionInterface;
+use Mcp\Server\Task\TaskStoreInterface;
 use Psr\Container\ContainerInterface;
 
 /**
  * @author Kyrian Obikwelu <koshnawaza@gmail.com>
  */
 final class ReferenceHandler implements ReferenceHandlerInterface
 {
+    /**
+     * @param ?TaskStoreInterface $taskStore the store handlers create tasks in, when the Tasks extension is enabled
+     */
     public function __construct(
         private readonly ?ContainerInterface $container = null,
+        private readonly ?TaskStoreInterface $taskStore = null,
     ) {
     }
 
@@ -109,7 +114,12 @@ private function prepareArguments(\ReflectionFunctionAbstract $reflection, array
                 $typeName = $type->getName();
 
                 if (RequestContext::class === $typeName && isset($arguments['_session'], $arguments['_request'])) {
-                    $finalArgs[$paramPosition] = new RequestContext($arguments['_session'], $arguments['_request']);
+                    $finalArgs[$paramPosition] = new RequestContext($arguments['_session'], $arguments['_request'], $this->taskStore);
+                    continue;
+                }
+
+                if (TaskStoreInterface::class === $typeName && null !== $this->taskStore) {
+                    $finalArgs[$paramPosition] = $this->taskStore;
                     continue;
                 }
 

src/Client.php

@@ -36,15 +36,21 @@
 use Mcp\Schema\Request\PingRequest;
 use Mcp\Schema\Request\ReadResourceRequest;
 use Mcp\Schema\Request\SetLogLevelRequest;
+use Mcp\Schema\Request\TasksCancelRequest;
+use Mcp\Schema\Request\TasksGetRequest;
+use Mcp\Schema\Request\TasksUpdateRequest;
 use Mcp\Schema\ResourceReference;
 use Mcp\Schema\Result\CallToolResult;
 use Mcp\Schema\Result\CompletionCompleteResult;
+use Mcp\Schema\Result\CreateTaskResult;
 use Mcp\Schema\Result\GetPromptResult;
 use Mcp\Schema\Result\ListPromptsResult;
 use Mcp\Schema\Result\ListResourcesResult;
 use Mcp\Schema\Result\ListResourceTemplatesResult;
 use Mcp\Schema\Result\ListToolsResult;
 use Mcp\Schema\Result\ReadResourceResult;
+use Mcp\Schema\Result\TaskResult;
+use Mcp\Schema\Task;
 use Psr\Log\LoggerInterface;
 use Psr\Log\NullLogger;
 
@@ -181,18 +187,24 @@ public function listTools(?string $cursor = null): ListToolsResult
     /**
      * Call a tool on the server.
      *
+     * A server with the Tasks extension may answer with a {@see CreateTaskResult}
+     * instead of the tool's output when the client declared the extension; poll
+     * it with {@see self::getTask()}.
+     *
      * @param string                                                                  $name       Tool name
      * @param array<string, mixed>                                                    $arguments  Tool arguments
      * @param (callable(float $progress, ?float $total, ?string $message): void)|null $onProgress
      *                                                                                            Optional callback for progress updates
      */
-    public function callTool(string $name, array $arguments = [], ?callable $onProgress = null): CallToolResult
+    public function callTool(string $name, array $arguments = [], ?callable $onProgress = null): CallToolResult|CreateTaskResult
     {
         $request = new CallToolRequest($name, $arguments);
 
         $response = $this->sendRequest($request, $onProgress);
 
-        return CallToolResult::fromArray($response->result);
+        return CreateTaskResult::describes($response->result)
+            ? CreateTaskResult::fromArray($response->result)
+            : CallToolResult::fromArray($response->result);
     }
 
     /**
@@ -222,17 +234,21 @@ public function listResourceTemplates(?string $cursor = null): ListResourceTempl
     /**
      * Read a resource by URI.
      *
+     * May answer with a {@see CreateTaskResult}, see {@see self::callTool()}.
+     *
      * @param string                                                                  $uri        The resource URI
      * @param (callable(float $progress, ?float $total, ?string $message): void)|null $onProgress
      *                                                                                            Optional callback for progress updates
      */
-    public function readResource(string $uri, ?callable $onProgress = null): ReadResourceResult
+    public function readResource(string $uri, ?callable $onProgress = null): ReadResourceResult|CreateTaskResult
     {
         $request = new ReadResourceRequest($uri);
 
         $response = $this->sendRequest($request, $onProgress);
 
-        return ReadResourceResult::fromArray($response->result);
+        return CreateTaskResult::describes($response->result)
+            ? CreateTaskResult::fromArray($response->result)
+            : ReadResourceResult::fromArray($response->result);
     }
 
     /**
@@ -250,18 +266,55 @@ public function listPrompts(?string $cursor = null): ListPromptsResult
     /**
      * Get a prompt from the server.
      *
+     * May answer with a {@see CreateTaskResult}, see {@see self::callTool()}.
+     *
      * @param string                                                                  $name       Prompt name
      * @param array<string, string>                                                   $arguments  Prompt arguments
      * @param (callable(float $progress, ?float $total, ?string $message): void)|null $onProgress
      *                                                                                            Optional callback for progress updates
      */
-    public function getPrompt(string $name, array $arguments = [], ?callable $onProgress = null): GetPromptResult
+    public function getPrompt(string $name, array $arguments = [], ?callable $onProgress = null): GetPromptResult|CreateTaskResult
     {
         $request = new GetPromptRequest($name, $arguments);
 
         $response = $this->sendRequest($request, $onProgress);
 
-        return GetPromptResult::fromArray($response->result);
+        return CreateTaskResult::describes($response->result)
+            ? CreateTaskResult::fromArray($response->result)
+            : GetPromptResult::fromArray($response->result);
+    }
+
+    /**
+     * The current state of a task (Tasks extension, `tasks/get`).
+     *
+     * Poll it at the task's `pollIntervalMs` until {@see Schema\Enum\TaskStatus::isTerminal()};
+     * a completed task carries the original request's result, an
+     * `input_required` one what it is waiting for, to answer with {@see self::updateTask()}.
+     */
+    public function getTask(string $taskId): Task
+    {
+        $response = $this->sendRequest(new TasksGetRequest($taskId));
+
+        return TaskResult::fromArray($response->result)->task;
+    }
+
+    /**
+     * Answers what a task asked for (Tasks extension, `tasks/update`).
+     *
+     * @param array<string, mixed> $inputResponses keyed as the task's `inputRequests` were
+     */
+    public function updateTask(string $taskId, array $inputResponses): void
+    {
+        $this->sendRequest(new TasksUpdateRequest($taskId, $inputResponses));
+    }
+
+    /**
+     * Asks the server to cancel a task (Tasks extension, `tasks/cancel`).
+     * Cooperative: the task may still finish.
+     */
+    public function cancelTask(string $taskId): void
+    {
+        $this->sendRequest(new TasksCancelRequest($taskId));
     }
 
     /**

src/JsonRpc/MessageFactory.php

@@ -95,10 +95,12 @@ public function __construct(
 
     /**
      * Creates a new Factory instance with all the protocol's default messages.
+     *
+     * @param list<class-string<Request>|class-string<Notification>> $additional message classes an extension defines
      */
-    public static function make(int $maxBatchSize = self::DEFAULT_MAX_BATCH_SIZE): self
+    public static function make(int $maxBatchSize = self::DEFAULT_MAX_BATCH_SIZE, array $additional = []): self
     {
-        return new self(self::REGISTERED_MESSAGES, $maxBatchSize);
+        return new self([...self::REGISTERED_MESSAGES, ...$additional], $maxBatchSize);
     }
 
     /**

src/Schema/ClientCapabilities.php

@@ -188,7 +188,12 @@ public function jsonSerialize(): array|object
         }
 
         if ($this->extensions) {
-            $data['extensions'] = (object) $this->extensions;
+            // Each entry is a settings *object*; an extension with no settings
+            // declares `{}`, and an empty PHP array would serialize as `[]`.
+            $data['extensions'] = (object) array_map(
+                static fn (mixed $settings): mixed => \is_array($settings) ? (object) $settings : $settings,
+                $this->extensions,
+            );
         }
 
         return $data ?: new \stdClass();

src/Schema/Enum/ResultType.php

@@ -0,0 +1,33 @@
+<?php
+
+/*
+ * This file is part of the official PHP MCP SDK.
+ *
+ * A collaboration between Symfony and the PHP Foundation.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Mcp\Schema\Enum;
+
+/**
+ * Tells the client how to read a result before it looks at the body.
+ *
+ * Required from 2026-07-28, where a request may come back finished or asking
+ * for input. A client seeing no `resultType` MUST read it as
+ * {@see self::Complete}.
+ *
+ * @author Christopher Hertel <mail@christopher-hertel.de>
+ */
+enum ResultType: string
+{
+    /** The request finished; the result holds the final content. */
+    case Complete = 'complete';
+
+    /** The request needs more input before it can finish (MRTR). */
+    case InputRequired = 'input_required';
+
+    /** The request became a task; the result is the handle to poll (Tasks extension). */
+    case Task = 'task';
+}