[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, and a `TaskContext`
handed to handlers for creating tasks — refused with -32021 for a client that
did not declare the extension.

The core stays extension-agnostic: `MethodProvidingExtensionInterface` and
`ArgumentProvidingExtensionInterface` let an extension register its messages,
handlers and injectable handler arguments; the core handlers pass any
`ResultInterface` through; a `MissingRequiredClientCapabilityException` from
handler code becomes -32021; `Client::request()` sends any request. On the
client, `TaskClient` speaks the extension. Covered end to end by an integration
test against a stdio fixture server. Extension settings serialize as `{}`
rather than `[]` when empty.

Author: chr-hertel

CHANGELOG.md

@@ -20,6 +20,8 @@ All notable changes to `mcp/sdk` will be documented in this file.
   * Deprecate Roots, Sampling and Logging (SEP-2577, earliest removal `2027-07-28`); they keep working but trigger a deprecation notice.
   * [BC Break] Answer a not-found subject with `-32602` instead of `-32002` (SEP-2164): `resources/read` picks the code by revision (`-32602` from `2026-07-28` on), `prompts/get`, `completion/complete` and `tools/call` switch on every revision. Adds `ProtocolVersion::usesInvalidParamsForResourceNotFound()`.
   * [BC Break] A list-shaped tool result is only sent as `structuredContent` on `2026-07-28`+; older revisions keep the JSON-encoded value in `content`.
+* Add the Tasks extension (SEP-2663, `io.modelcontextprotocol/tasks`): a server hands back a durable handle instead of holding a connection open — `Mcp\Schema\Task` and `TaskStatus`, `ResultType::Task`, the flat `CreateTaskResult` / `TaskResult` wire shapes, the `tasks/get` / `tasks/update` / `tasks/cancel` surface, and `TaskStoreInterface` with `InMemoryTaskStore` and `Psr16TaskStore` (what PHP-FPM needs). Enable with `Builder::enableExtension(new TasksExtension($store))`; a handler declares a `TaskContext` parameter and creates a task through `TaskContext::create()` after `isSupported()` — a task for a client that did not declare the extension is refused with `-32021`. Advancing a task is the application's job. On the client, `enableExtension(new TasksExtension())` declares it and `Client\Task\TaskClient` speaks it.
+* Let an extension reach handler code without the core knowing it: `ArgumentProvidingExtensionInterface` hands handlers objects of the extension's own, injected like a `RequestContext` and left out of the generated schemas; the tool, prompt and resource handlers pass any `ResultInterface` a handler returns through untouched; a `MissingRequiredClientCapabilityException` thrown from handler code is answered as `-32021`; `Client::request()` sends any request.
 * [BC Break] Add the extensions framework (SEP-2133) MCP Apps sits on: `ExtensionInterface::getId()` returns an `ExtensionIdentifier` value object, and the interface gains `getMessages()`/`getRequestHandlers()` (extend `AbstractExtension` to skip both). `MessageFactory::make()` takes an `$additional` message list; `RequestHandlerInterface`'s result template is covariant. `ServerExtensionInterface` is replaced by the side-agnostic `Schema\Extension\ExtensionInterface`.
 * Add client-side extension negotiation: `ClientGateway::supportsExtension()`, `Client\Builder::enableExtension()`, `ClientCapabilities::withExtensions()`.
 * Add sampling-with-tools: sampling requests can carry tools and tool-choice preferences, messages support tool-use/tool-result blocks, and clients advertise `sampling.context`/`sampling.tools` (`ClientGateway::supportsSamplingTools()`/`supportsSamplingContext()`). Requests violating the tool-flow rules are rejected with a JSON-RPC error.

docs/advanced/extensions.md

@@ -48,6 +48,120 @@ public function getWeather(string $city, RequestContext $context): string
 }
 ```
 
+An extension that hands handlers an object of its own implements
+`ArgumentProvidingExtensionInterface` on top: a handler declaring a parameter
+of a provided type receives it for the request being served, the way it
+receives a `RequestContext` — and it stays out of the generated input schemas.
+
+## 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. The extension
+hands handlers a `TaskContext` — declare the parameter and it arrives, like a
+`RequestContext` does:
+
+```php
+use Mcp\Schema\Result\CreateTaskResult;
+use Mcp\Server\Task\TaskContext;
+
+static function (TaskContext $tasks) use ($queue): CreateTaskResult|string {
+    if (!$tasks->isSupported()) {
+        return runSynchronously();          // the client cannot poll, so answer now
+    }
+
+    $created = $tasks->create(ttlMs: 600_000, pollIntervalMs: 1000);
+    $queue->push($created->task->taskId);   // a worker calls $store->save() as it progresses
+
+    return $created;
+}
+```
+
+`create()` 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` cannot redeem a handle, so `create()` refuses
+with `-32021` (missing required client capability) instead of handing one out —
+the right answer for a handler whose task support is *required*, and what
+`isSupported()` 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 `TaskContext::getStore()`) 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. `TaskClient` wraps a connected `Client`: its `callTool()`,
+`getPrompt()` and `readResource()` return a `CreateTaskResult` when the server
+chose to answer with a task, and `get()` / `update()` / `cancel()` drive it:
+
+```php
+use Mcp\Client;
+use Mcp\Client\Task\TaskClient;
+use Mcp\Schema\Result\CallToolResult;
+use Mcp\Schema\Result\CreateTaskResult;
+use Mcp\Server\Task\TasksExtension;
+
+$client = Client::builder()
+    ->enableExtension(new TasksExtension())
+    ->build();
+$client->connect($transport);
+
+$tasks = new TaskClient($client);
+$result = $tasks->callTool('long_job');
+
+if ($result instanceof CreateTaskResult) {
+    do {
+        usleep(1000 * ($result->task->pollIntervalMs ?? 1000));
+        $task = $tasks->get($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
+`update($taskId, ['<key>' => $answer])`, keyed as the requests were, and
+`cancel($taskId)` asks the server to stop. The core `Client` itself stays
+task-agnostic; `Client::request()` sends any request for code like this.
+
 ## MCP Apps (`io.modelcontextprotocol/ui`)
 
 The [MCP Apps extension][ext-apps] lets servers expose interactive HTML UIs as
@@ -158,3 +272,4 @@ working minimal view is included in
 [`examples/server/mcp-apps/weather-app.html`](https://github.com/modelcontextprotocol/php-sdk/blob/main/examples/server/mcp-apps/weather-app.html).
 
 [ext-apps]: https://github.com/modelcontextprotocol/ext-apps
+[ext-tasks]: https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2663

src/Capability/Discovery/SchemaGenerator.php

@@ -60,8 +60,14 @@
  */
 final class SchemaGenerator implements SchemaGeneratorInterface
 {
+    /**
+     * @param list<class-string> $injectedTypes parameter types the runtime injects rather than the caller supplies,
+     *                                          on top of {@see InjectableParameters} — an extension's, say — and
+     *                                          which therefore do not belong in a schema
+     */
     public function __construct(
         private readonly DocBlockParser $docBlockParser,
+        private readonly array $injectedTypes = [],
     ) {
     }
 
@@ -528,10 +534,12 @@ private function parseParametersInfo(\ReflectionMethod|\ReflectionFunction $refl
         foreach ($reflection->getParameters() as $rp) {
             $reflectionType = $rp->getType();
 
-            if ($reflectionType instanceof \ReflectionNamedType && !$reflectionType->isBuiltin()
-                && InjectableParameters::supports($reflectionType->getName())
-            ) {
-                continue;
+            if ($reflectionType instanceof \ReflectionNamedType && !$reflectionType->isBuiltin()) {
+                $typeName = $reflectionType->getName();
+
+                if (InjectableParameters::supports($typeName) || \in_array($typeName, $this->injectedTypes, true)) {
+                    continue;
+                }
             }
 
             $paramName = $rp->getName();

src/Capability/Registry/ReferenceHandler.php

@@ -13,6 +13,7 @@
 
 use Mcp\Exception\InvalidArgumentException;
 use Mcp\Exception\RegistryException;
+use Mcp\Schema\JsonRpc\Request;
 use Mcp\Server\Session\SessionInterface;
 use Psr\Container\ContainerInterface;
 
@@ -21,8 +22,14 @@
  */
 final class ReferenceHandler implements ReferenceHandlerInterface
 {
+    /**
+     * @param array<class-string, callable(SessionInterface, Request): object> $argumentProviders builders for further
+     *                                                                                            injectable parameter types,
+     *                                                                                            e.g. an extension's
+     */
     public function __construct(
         private readonly ?ContainerInterface $container = null,
+        private readonly array $argumentProviders = [],
     ) {
     }
 
@@ -109,6 +116,15 @@ private function prepareArguments(\ReflectionFunctionAbstract $reflection, array
                     $finalArgs[$paramPosition] = $injected;
                     continue;
                 }
+
+                // An extension may contribute further injectable types; the
+                // core stays unaware of what they are.
+                $typeName = $type->getName();
+
+                if (isset($this->argumentProviders[$typeName], $arguments['_session'], $arguments['_request'])) {
+                    $finalArgs[$paramPosition] = ($this->argumentProviders[$typeName])($arguments['_session'], $arguments['_request']);
+                    continue;
+                }
             }
 
             if (isset($arguments[$paramName])) {

src/Client.php

@@ -354,6 +354,22 @@ private function sendRequest(Request $request, ?callable $onProgress = null): Re
         return $response;
     }
 
+    /**
+     * Sends any request and returns the raw response — the way to speak a
+     * method the typed API does not cover, such as an extension's.
+     *
+     * @param (callable(float $progress, ?float $total, ?string $message): void)|null $onProgress
+     *                                                                                            Optional callback for progress updates
+     *
+     * @return Response<mixed>
+     *
+     * @throws RequestException|ConnectionException
+     */
+    public function request(Request $request, ?callable $onProgress = null): Response
+    {
+        return $this->sendRequest($request, $onProgress);
+    }
+
     /**
      * Disconnect from the server.
      */

src/Client/Task/TaskClient.php

@@ -0,0 +1,122 @@
+<?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\Client\Task;
+
+use Mcp\Client;
+use Mcp\Schema\Request\CallToolRequest;
+use Mcp\Schema\Request\GetPromptRequest;
+use Mcp\Schema\Request\ReadResourceRequest;
+use Mcp\Schema\Request\TasksCancelRequest;
+use Mcp\Schema\Request\TasksGetRequest;
+use Mcp\Schema\Request\TasksUpdateRequest;
+use Mcp\Schema\Result\CallToolResult;
+use Mcp\Schema\Result\CreateTaskResult;
+use Mcp\Schema\Result\GetPromptResult;
+use Mcp\Schema\Result\ReadResourceResult;
+use Mcp\Schema\Result\TaskResult;
+use Mcp\Schema\Task;
+
+/**
+ * The client side of the Tasks extension (SEP-2663), on top of a connected
+ * {@see Client} that declared it.
+ *
+ * ```php
+ * $client = Client::builder()->enableExtension(new TasksExtension())->build();
+ * $client->connect($transport);
+ *
+ * $tasks = new TaskClient($client);
+ * $result = $tasks->callTool('long_job');
+ *
+ * if ($result instanceof CreateTaskResult) {
+ *     do {
+ *         usleep(1000 * ($result->task->pollIntervalMs ?? 1000));
+ *         $task = $tasks->get($result->task->taskId);
+ *     } while (!$task->status->isTerminal());
+ * }
+ * ```
+ *
+ * The core client's `callTool()`, `getPrompt()` and `readResource()` expect
+ * the answer itself; these variants accept a task handle in its place, which a
+ * server may send once the extension is declared.
+ *
+ * @author Christopher Hertel <mail@christopher-hertel.de>
+ */
+final class TaskClient
+{
+    public function __construct(
+        private readonly Client $client,
+    ) {
+    }
+
+    /**
+     * @param array<string, mixed>                                                    $arguments
+     * @param (callable(float $progress, ?float $total, ?string $message): void)|null $onProgress
+     */
+    public function callTool(string $name, array $arguments = [], ?callable $onProgress = null): CallToolResult|CreateTaskResult
+    {
+        $result = $this->client->request(new CallToolRequest($name, $arguments), $onProgress)->result;
+
+        return CreateTaskResult::describes($result) ? CreateTaskResult::fromArray($result) : CallToolResult::fromArray($result);
+    }
+
+    /**
+     * @param array<string, string>                                                   $arguments
+     * @param (callable(float $progress, ?float $total, ?string $message): void)|null $onProgress
+     */
+    public function getPrompt(string $name, array $arguments = [], ?callable $onProgress = null): GetPromptResult|CreateTaskResult
+    {
+        $result = $this->client->request(new GetPromptRequest($name, $arguments), $onProgress)->result;
+
+        return CreateTaskResult::describes($result) ? CreateTaskResult::fromArray($result) : GetPromptResult::fromArray($result);
+    }
+
+    /**
+     * @param (callable(float $progress, ?float $total, ?string $message): void)|null $onProgress
+     */
+    public function readResource(string $uri, ?callable $onProgress = null): ReadResourceResult|CreateTaskResult
+    {
+        $result = $this->client->request(new ReadResourceRequest($uri), $onProgress)->result;
+
+        return CreateTaskResult::describes($result) ? CreateTaskResult::fromArray($result) : ReadResourceResult::fromArray($result);
+    }
+
+    /**
+     * The current state of a task (`tasks/get`).
+     *
+     * Poll it at the task's `pollIntervalMs` until {@see \Mcp\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::update()}.
+     */
+    public function get(string $taskId): Task
+    {
+        return TaskResult::fromArray($this->client->request(new TasksGetRequest($taskId))->result)->task;
+    }
+
+    /**
+     * Answers what a task asked for (`tasks/update`).
+     *
+     * @param array<string, mixed> $inputResponses keyed as the task's `inputRequests` were
+     */
+    public function update(string $taskId, array $inputResponses): void
+    {
+        $this->client->request(new TasksUpdateRequest($taskId, $inputResponses));
+    }
+
+    /**
+     * Asks the server to cancel a task (`tasks/cancel`). Cooperative: the task
+     * may still finish.
+     */
+    public function cancel(string $taskId): void
+    {
+        $this->client->request(new TasksCancelRequest($taskId));
+    }
+}

src/Schema/Enum/ResultType.php

@@ -27,4 +27,7 @@ enum ResultType: string
 
     /** 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';
 }