Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
24 commits
Select commit Hold shift + click to select a range
856ebd3
feat: Tasks extension for server and client (ext/tasks subpaths)
mattzcarey Oct 23, 2026
ef7413c
fix(server): keep in-memory tasks whose TTL exceeds the setTimeout limit
mattzcarey Oct 27, 2026
b7cebca
fix(server): settle every requireInput wait in the in-memory task store
mattzcarey Oct 27, 2026
db58c44
docs(tasks): correct the Tasks guides, changeset and comments
mattzcarey Oct 27, 2026
b5b365d
fix(client): await onUpdate in TasksClientExtension.waitFor
mattzcarey Oct 27, 2026
46bc34c
docs(tasks): name only published entry points in the changeset
mattzcarey Oct 27, 2026
9c282a9
fix(server): bind tasks to a user-level principal; serve Tasks on 202…
mattzcarey Oct 27, 2026
0dc9f6a
test(conformance): serve the Tasks extension and its fixtures
mattzcarey Oct 27, 2026
9398ce8
fix(server): refuse malformed tasks/update and cancel refused task ha…
mattzcarey Oct 27, 2026
09ec0f9
fix(server): give in-memory task aborts a reason that says why
mattzcarey Oct 27, 2026
21fc843
docs(tasks): the client example connects on 2026-07-28; trim the wire…
mattzcarey Oct 27, 2026
4fb0ae6
feat(core): publish the Tasks wire definitions at @modelcontextprotoc…
mattzcarey Oct 27, 2026
091c5e8
docs(tasks): mark the ext/tasks subpaths and their exports @experimental
mattzcarey Nov 5, 2026
30e1eed
fix(server): a tool's MissingRequiredClientCapabilityError is a JSON-…
mattzcarey Nov 18, 2026
1a48916
test(e2e): a tool's -32021 is answered HTTP 400 on the modern entry; …
mattzcarey Nov 18, 2026
20ed8b1
test(e2e): move the Tasks end-to-end tests to test/e2e with requireme…
mattzcarey Nov 19, 2026
088c33d
fix(tasks): check input requests and answers; let an outputSchema too…
mattzcarey Nov 19, 2026
fdafba3
refactor(tasks): stop re-exporting the wire schemas from the server a…
mattzcarey Nov 19, 2026
509e422
docs: name both errors a tool handler can propagate, everywhere error…
mattzcarey Nov 19, 2026
f54eff4
docs(tasks): the example and guide clients declare the elicitation ca…
mattzcarey Nov 19, 2026
f9ba515
fix(server): pass a tool's -32021 through on 2026-07-28 only
mattzcarey Nov 19, 2026
56107bb
test(tasks): on 2025-11-25 a task tool's refusal is a tool error
mattzcarey Nov 19, 2026
0b95fb2
test(e2e): link the -32021 requirement to the 2025-11-25 one it super…
mattzcarey Nov 19, 2026
fb0d953
docs(tasks): say the task handle goes out with an empty content array
mattzcarey Nov 19, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 15 additions & 0 deletions .changeset/tasks-extension.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
---
'@modelcontextprotocol/core': minor
'@modelcontextprotocol/client': minor
'@modelcontextprotocol/server': minor
---

The MCP Tasks extension (`io.modelcontextprotocol/tasks`) as a pair of extensions. The `ext/tasks` subpaths of server, client and core are experimental: they may change in a minor release while the extensions SEPs settle.

`@modelcontextprotocol/server/ext/tasks`: `new TasksExtension(store)` in `McpServerOptions.extensions` advertises the capability, serves `tasks/get`, `tasks/update` and `tasks/cancel`, gates task handles on the client capability (`-32021`), binds each task to the creating request's principal (`principal` option; by default the OAuth client id plus the token subject), serves its methods on 2026-07-28 only (`-32601` on 2025-11-25), and offers `tasks.create(ctx)` for a tool handler to answer with a task handle. `TaskStore` (create / get / update / cancel over JSON) is the interface a server implements over its own state and execution; `InMemoryTaskStore` is the in-process reference with a writer `handle` for reporting status, requesting input, and settling. It refuses an input request that needs a client capability the creating request did not declare, and answers `-32602` to a `tasks/update` answer that is not a valid result for the request it answers. Task access is by principal only: a tool's `scopeChallenge` is not re-run on `tasks/*`.

`@modelcontextprotocol/client/ext/tasks`: `new TasksClientExtension()` in `ClientOptions.extensions` declares the capability on every request, accepts task handles on `tools/call`, and wraps the extension's methods: `callTool` (a task handle or the plain result; it sends `tools/call` directly, without `client.callTool`'s `Mcp-Param-*` header mirroring or `outputSchema` validation), `get`, `update`, `cancel`, and `waitFor`, which polls at the server's suggested interval to a terminal snapshot.

`@modelcontextprotocol/core/ext/tasks`: the extension's wire constants (`TASKS_EXTENSION_ID`, `TASK_STATUSES`), zod schemas and the types inferred from them, runtime-neutral. The server and client subpaths re-export the types and constants, plus the SDK's precise `InputRequest(s)` / `InputResponse(s)` types that `requireInput` and `update` take.

`McpServer` no longer validates a tool result of another kind, such as a task handle, against the tool's `outputSchema`: like an `input_required` result, it is not the tool's final output.
5 changes: 5 additions & 0 deletions .changeset/tool-missing-client-capability.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
'@modelcontextprotocol/server': patch
---

On a 2026-07-28 request, a tool that throws `MissingRequiredClientCapabilityError` now answers `tools/call` with JSON-RPC error `-32021` and its `requiredCapabilities`, as that revision requires, instead of an `isError` tool result. This changes what such a tool returns for every `McpServer` on 2026-07-28: a client that read the message from the tool result now gets a `ProtocolError` with code `-32021`. On 2025-11-25, which does not define that code, the tool error is unchanged. Over HTTP the response status is 400, unless the response stream is already open. The same applies to a `-32021` a tool relays from a downstream server: catch and translate it instead of rethrowing, because its `requiredCapabilities` describe the downstream hop.
2 changes: 2 additions & 0 deletions docs/.vitepress/nav.ts
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,7 @@ export const guideSidebar: DefaultTheme.SidebarItem[] = [
{ text: 'Elicitation', link: '/servers/elicitation' },
{ text: 'Sampling (sunset)', link: '/servers/sampling' },
{ text: 'Input required', link: '/servers/input-required' },
{ text: 'Tasks (extension)', link: '/servers/tasks' },
{ text: 'Notifications', link: '/servers/notifications' },
{ text: 'Errors', link: '/servers/errors' }
]
Expand All @@ -54,6 +55,7 @@ export const guideSidebar: DefaultTheme.SidebarItem[] = [
{ text: 'Handle server requests', link: '/clients/server-requests' },
{ text: 'Roots (sunset)', link: '/clients/roots' },
{ text: 'Subscriptions', link: '/clients/subscriptions' },
{ text: 'Tasks (extension)', link: '/clients/tasks' },
{ text: 'OAuth', link: '/clients/oauth' },
{ text: 'Machine auth', link: '/clients/machine-auth' },
{ text: 'Middleware', link: '/clients/middleware' },
Expand Down
87 changes: 87 additions & 0 deletions docs/clients/tasks.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,87 @@
---
shape: how-to
---

# Tasks (extension)

::: warning Experimental
The `@modelcontextprotocol/client/ext/tasks` subpath (and `@modelcontextprotocol/core/ext/tasks`) is experimental: it may change in a minor release while the extensions SEPs settle.
:::

The [MCP Tasks extension](https://github.com/modelcontextprotocol/ext-tasks) (`io.modelcontextprotocol/tasks`) lets a server answer a tool call with a **task handle** instead of blocking: you poll `tasks/get`, answer `tasks/update`, and stop with `tasks/cancel`. `@modelcontextprotocol/client/ext/tasks` is the client side of that wire, as a [client extension](../advanced/extensions.md). The server side is [Tasks (extension)](../servers/tasks.md).

## Install the extension

One extension instance serves one client; pass it at construction.

```ts
import { Client } from '@modelcontextprotocol/client';
import { TasksClientExtension } from '@modelcontextprotocol/client/ext/tasks';

const tasks = new TasksClientExtension();
const client = new Client({ name: 'report-client', version: '1.0.0' }, { versionNegotiation: { mode: 'auto' }, capabilities: { elicitation: { form: {} } }, extensions: [tasks] });
await client.connect(transport);
```

The client declares `io.modelcontextprotocol/tasks` in the capabilities envelope of every request — the server refuses task handles to clients that do not — and accepts `resultType: "task"` on `tools/call`, which the plain `client.callTool` cannot describe. Declare the capabilities for the input you can answer, such as `elicitation` above: a task may only ask for what the request that created it declared.

## Call a tool that may become a task

`tasks.callTool` returns a discriminated outcome: a task handle to follow, or the ordinary result for tools that answered synchronously.

It sends `tools/call` directly, without what `client.callTool` adds: it does not mirror `x-mcp-header` arguments into `Mcp-Param-*` headers, so a tool that declares them is refused over HTTP, and it does not validate a synchronous result's `structuredContent` against the tool's `outputSchema`. Call such tools with `client.callTool`.

```ts
const outcome = await tasks.callTool({ name: 'send_report', arguments: { to: 'ops' } });
if (outcome.kind === 'result') {
console.log(outcome.result.content);
} else {
console.log(outcome.task.taskId, outcome.task.status, outcome.task.pollIntervalMs);
}
```

## Poll to the end

`waitFor` polls `tasks/get` at the server's suggested `pollIntervalMs` until the task is terminal. Every snapshot passes through `onUpdate`, which is where an `input_required` task gets answered.

```ts
const done = await tasks.waitFor(outcome.task.taskId, {
signal: controller.signal,
onUpdate: async task => {
if (task.status === 'input_required') {
const answers = await askUser(task.inputRequests);
await tasks.update(task.taskId, answers);
}
}
});

switch (done.status) {
case 'completed':
console.log(done.result);
break;
case 'failed':
console.error(done.error);
break;
case 'cancelled':
break;
}
```

Aborting the signal stops polling and nothing else. Cancelling the task is a separate, cooperative call: `await tasks.cancel(taskId)` resolves on acknowledgement, and the task may still settle `completed` or `failed`.

## The raw methods

| Method | Wire | Returns |
| -------------------------------------- | -------------- | --------------------------------------------------------------------- |
| `tasks.get(taskId)` | `tasks/get` | The `DetailedTask` snapshot: result, error, or input requests inlined |
| `tasks.update(taskId, inputResponses)` | `tasks/update` | Resolves on acknowledgement; partial answers are accepted |
| `tasks.cancel(taskId)` | `tasks/cancel` | Resolves on acknowledgement |

Each takes the usual `RequestOptions` (`signal`, `timeout`) as a last argument.

## Recap

- `new TasksClientExtension()` in `ClientOptions.extensions`; one instance per client.
- `tasks.callTool(params)` yields `{ kind: 'task', task }` or `{ kind: 'result', result }`.
- `tasks.waitFor(taskId, { onUpdate, signal })` polls at the server's interval to a terminal snapshot.
- `get`, `update`, `cancel` are the extension's three methods, one to one.
10 changes: 5 additions & 5 deletions docs/servers/errors.md
Original file line number Diff line number Diff line change
Expand Up @@ -61,7 +61,7 @@ The model reads the message, sees `welcome` in it, and retries with an id that e

## Let a thrown exception become a tool error

Throw instead: the SDK catches anything a tool handler throws and converts it to the same `isError: true` shape.
Throw instead: the SDK catches what a tool handler throws and converts it to the same `isError: true` shape. The two exceptions reach the client as protocol errors: `UrlElicitationRequiredError` on 2025-11-25 and `MissingRequiredClientCapabilityError` on 2026-07-28 (see [Throw a protocol error](#throw-a-protocol-error)).

```ts source="../../examples/guides/servers/errors.examples.ts#registerTool_throw"
server.registerTool(
Expand Down Expand Up @@ -147,7 +147,7 @@ Pick by audience. The model drives `tools/call`, so a failure it can recover fro

The handler decides which channel exists:

- A tool handler produces only tool errors. The SDK converts every exception it throws — including a thrown `ProtocolError` — into an `isError: true` result. `UrlElicitationRequiredError` is the one exception; it propagates as a JSON-RPC error so the host can open the URL — see [Elicitation](./elicitation.md).
- A tool handler produces only tool errors. The SDK converts every exception it throws — including a thrown `ProtocolError` — into an `isError: true` result. `UrlElicitationRequiredError` and `MissingRequiredClientCapabilityError` are the two exceptions. On 2025-11-25 the first propagates as a JSON-RPC error so the host can open the URL — see [Elicitation](./elicitation.md); on 2026-07-28 the second tells the client which capability to declare.
- A resource, prompt, or completion callback produces only protocol errors. Throw a `ProtocolError`.

## Use the typed error subclasses
Expand Down Expand Up @@ -175,9 +175,9 @@ The error carries the requested URI in `data` and the code the spec mandates for

Three more subclasses cover the other structured protocol errors:

- `UrlElicitationRequiredError(elicitations)` — `-32042`; the only error a tool handler can propagate. See [Elicitation](./elicitation.md).
- `UrlElicitationRequiredError(elicitations)` — `-32042`; a tool handler can propagate it on 2025-11-25. On 2026-07-28 return `inputRequired.elicitUrl(...)` instead. See [Elicitation](./elicitation.md).
- `UnsupportedProtocolVersionError({ supported, requested })` — `-32022`; `data.supported` lets the peer pick a version and retry.
- `MissingRequiredClientCapabilityError({ requiredCapabilities })` — `-32021`; `data.requiredCapabilities` names exactly what the client must declare.
- `MissingRequiredClientCapabilityError({ requiredCapabilities })` — `-32021`; `data.requiredCapabilities` names exactly what the client must declare. A tool handler can propagate it on 2026-07-28, where over HTTP it is answered with status 400 unless the response stream is already open; on 2025-11-25 it becomes a tool error like any other throw.

Match these by `code` and `data` shape when peers may run pre-brand SDK copies or hand you plain wire shapes; on brand-aware releases `instanceof` also matches across separately bundled copies of the SDK. The same check is available as an explicit static guard — `ProtocolError.isInstance(err)`, `ResourceNotFoundError.isInstance(err)` — which narrows in TypeScript and reads the same brand.

Expand All @@ -203,7 +203,7 @@ Match these by `code` and `data` shape when peers may run pre-brand SDK copies o

- `isError: true` is a successful JSON-RPC result carrying a tool failure the model reads and acts on.
- A tool handler that throws produces the same `isError: true` result; the exception's `message` becomes the `content` text.
- A tool handler cannot produce a protocol error — only `UrlElicitationRequiredError` escapes.
- A tool handler cannot produce a protocol error — only `UrlElicitationRequiredError` (2025-11-25) and `MissingRequiredClientCapabilityError` (2026-07-28) escape.
- `ProtocolError` and its subclasses, thrown from resource, prompt, and completion callbacks, become JSON-RPC error responses the model never sees.
- `ResourceNotFoundError` and the other subclasses pick the code and pack structured `data`; match them by `code` and `data` — or, on brand-aware releases, by `instanceof`.
- The table above lists every `ProtocolErrorCode` member.
Loading
Loading