Skip to content

feat: Tasks extension for server and client (ext/tasks subpaths) - #2782

Open
mattzcarey wants to merge 24 commits into
feat/skills-as-extensionfrom
feat/pluggable-task-workflow
Open

mattzcarey wants to merge 24 commits into
feat/skills-as-extensionfrom
feat/pluggable-task-workflow

Conversation

@mattzcarey

@mattzcarey mattzcarey commented Sep 10, 2026 •

Copy link
Copy Markdown
Member

Adds the Tasks extension (io.modelcontextprotocol/tasks, SEP-2663) as @modelcontextprotocol/server/ext/tasks and @modelcontextprotocol/client/ext/tasks, with the wire schemas and types in @modelcontextprotocol/core/ext/tasks. A tool answers with a task handle, and the client polls it to a result. Stacked on #3066; it also carries #3202's commits until that merges.

const store = new InMemoryTaskStore();
const tasks = new TasksExtension(store);
const server = new McpServer(info, { extensions: [tasks] });

server.registerTool('send_report', { inputSchema }, async ({ to }, ctx) => {
    const task = await tasks.create(ctx, { ttlMs: 3_600_000 });
    void sendReport(store.handle(task.taskId), to); // the server runs the work however it likes
    return task;
});

// client
const tasksClient = new TasksClientExtension();
const client = new Client(info, { versionNegotiation: { mode: 'auto' }, extensions: [tasksClient] });
const outcome = await tasksClient.callTool({ name: 'send_report', arguments: { to: 'ops' } });
if (outcome.kind === 'task') await tasksClient.waitFor(outcome.task.taskId);

The SDK handles the wire protocol; running the work is the server's:

  • TasksExtension advertises the capability, serves tasks/get, tasks/update and tasks/cancel, and refuses a request that did not declare the extension (-32021). It is served on 2026-07-28 only: on 2025-11-25 the methods answer -32601.
  • TaskStore is four methods (create, get, update, cancel) over the server's own state. InMemoryTaskStore is the in-process reference, with a writer handle for status, input requests and settling.
  • A task is bound to a principal: by default the OAuth client id plus authInfo.extra.sub, or the principal option. Another principal gets "Task not found". Access is by principal only; a tool's scopeChallenge is not re-run on tasks/*.
  • A task may only ask for input the creating request's client capabilities cover, and a tasks/update answer that is not a valid result for its request is refused with -32602.
  • TasksClientExtension wraps callTool, get, update and cancel, and adds waitFor. Its callTool sends tools/call directly, without client.callTool's Mcp-Param-* header mirroring or outputSchema validation.
  • McpServer no longer validates a result of another kind, such as a task handle, against the tool's outputSchema.
  • Everything under the three ext/tasks subpaths is @experimental: it may change in a minor release while the extensions SEPs settle.
  • Not implemented: notifications/tasks (subscriptions/listen cannot carry extension notifications (blocks notifications/tasks) #2569), so clients poll. Refs Implement SEP-2663: Tasks Extension #2189, v2: extension methods shadowed by legacy spec-method registry — custom tasks/get & tasks/cancel handlers unreachable (-32601 before handler lookup) #2598.

pnpm check:all, the build and the unit, integration and e2e suites ran on Node 24, and the nine tasks-* conformance scenarios pass. The e2e requirements tasks:* and typescript:tasks:* cover the flow on the createMcpHandler entry, and examples/ext-tasks runs end to end over stdio.

@changeset-bot

changeset-bot Bot commented Sep 10, 2026 •

Copy link
Copy Markdown

🦋 Changeset detected

Latest commit: fb0d953

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 6 packages
Name Type
@modelcontextprotocol/core Minor
@modelcontextprotocol/client Minor
@modelcontextprotocol/server Minor
@modelcontextprotocol/core-internal Patch
@modelcontextprotocol/server-legacy Minor
@modelcontextprotocol/codemod Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

@pkg-pr-new

pkg-pr-new Bot commented Sep 10, 2026 •

Copy link
Copy Markdown

Open in StackBlitz

@modelcontextprotocol/client

npm i https://pkg.pr.new/@modelcontextprotocol/client@2782

@modelcontextprotocol/codemod

npm i https://pkg.pr.new/@modelcontextprotocol/codemod@2782

@modelcontextprotocol/core

npm i https://pkg.pr.new/@modelcontextprotocol/core@2782

@modelcontextprotocol/server

npm i https://pkg.pr.new/@modelcontextprotocol/server@2782

@modelcontextprotocol/server-legacy

npm i https://pkg.pr.new/@modelcontextprotocol/server-legacy@2782

@modelcontextprotocol/express

npm i https://pkg.pr.new/@modelcontextprotocol/express@2782

@modelcontextprotocol/fastify

npm i https://pkg.pr.new/@modelcontextprotocol/fastify@2782

@modelcontextprotocol/hono

npm i https://pkg.pr.new/@modelcontextprotocol/hono@2782

@modelcontextprotocol/node

npm i https://pkg.pr.new/@modelcontextprotocol/node@2782

commit: fb0d953

@mattzcarey mattzcarey changed the title feat(tasks): server-side Tasks extension package with a pluggable execution engine feat(server): Tasks extension at @modelcontextprotocol/server/ext/tasks with a pluggable execution engine Sep 11, 2026
@mattzcarey
mattzcarey force-pushed the feat/pluggable-task-workflow branch from 774c3f9 to b04649e Compare September 17, 2026 07:24
@mattzcarey
mattzcarey changed the base branch from main to feat/server-extensions September 17, 2026 07:24
@mattzcarey mattzcarey changed the title feat(server): Tasks extension at @modelcontextprotocol/server/ext/tasks with a pluggable execution engine feat(server): Tasks extension at @modelcontextprotocol/server/ext/tasks Sep 17, 2026
@mattzcarey mattzcarey changed the title feat(server): Tasks extension at @modelcontextprotocol/server/ext/tasks feat: Tasks extension for server and client (ext/tasks subpaths) Sep 17, 2026
@mattzcarey
mattzcarey added this pull request to stack #2826 September 17, 2026 14:18
@mattzcarey
mattzcarey force-pushed the feat/pluggable-task-workflow branch from 46c22c6 to b6f148b Compare September 17, 2026 14:19
@mattzcarey
mattzcarey force-pushed the feat/pluggable-task-workflow branch from b6f148b to 100decd Compare September 17, 2026 14:23
@claude claude Bot added the v2 Ideas, requests and plans for v2 of the SDK which will incorporate major changes and fixes label Sep 23, 2026
@mattzcarey
mattzcarey force-pushed the feat/pluggable-task-workflow branch from 100decd to 92e5587 Compare October 8, 2026 21:41
@mattzcarey
mattzcarey marked this pull request as ready for review October 8, 2026 21:41
@mattzcarey
mattzcarey requested a review from a team as a code owner October 8, 2026 21:41
@mattzcarey
mattzcarey force-pushed the feat/pluggable-task-workflow branch from 92e5587 to 1e5cffb Compare October 8, 2026 21:46

@claude claude Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

2 optional notes from this repository's REVIEW.md or CLAUDE.md checks were not posted as comments, over this review's limit for such notes; they are on this commit's check card.

Findings marked 🟡 are optional suggestions and need no follow-up push.

Comment thread docs/servers/tasks.md Resolved
Comment thread docs/servers/tasks.md Resolved

@claude claude Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

3 optional suggestions (nits or notes on pre-existing code) were found and not posted.

Still open from earlier reviews (10):

If you have decided not to act on one of these findings, resolve its thread (a reply alone leaves it open) and the next review stops counting it. To review this commit again now, use Re-run on its "Claude Code Review" check.

@mattzcarey
mattzcarey force-pushed the feat/pluggable-task-workflow branch from 1e5cffb to ff1836d Compare October 8, 2026 23:10

@claude claude Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code review found no new issues

No new issues were found in this update; 8 findings from earlier reviews are still open above.

5 optional suggestions (nits or notes on pre-existing code) were found and not posted.

Still open from earlier reviews (8):

If you have decided not to act on one of these findings, resolve its thread (a reply alone leaves it open) and the next review stops counting it. To review this commit again now, use Re-run on its "Claude Code Review" check.

@modelcontextprotocol/server/ext/tasks adds TasksExtension(store): it
advertises io.modelcontextprotocol/tasks, serves tasks/get, tasks/update
and tasks/cancel, refuses requests that did not declare the extension
(-32021), and gives a tool handler tasks.create(ctx) to answer tools/call
with a task handle. TaskStore is the four-method interface a server
implements over its own task state; InMemoryTaskStore is the in-process
reference, with a writer handle (status, requireInput, complete, fail,
signal).

@modelcontextprotocol/client/ext/tasks adds TasksClientExtension:
callTool, get, update, cancel and waitFor, which polls tasks/get until a
terminal status.

Wire types and schemas live at @modelcontextprotocol/core-internal/ext/tasks.

examples/ext-tasks is a minimal in-process server and client: a bake_cake
tool on TasksExtension over an InMemoryTaskStore reports progress, asks
for input (input_required) and honours cancellation; the client follows
it with TasksClientExtension.waitFor, answers through tasks.update, and
cancels a second task.
InMemoryTaskStore passed ttlMs straight to setTimeout, which fires almost at
once for any delay above 2^31-1 ms (about 24.8 days), so such a task was
purged right after creation and its signal aborted. Wait the TTL out in
steps of at most that delay.
handle.complete and handle.fail left an outstanding requireInput promise
pending until the TTL purge, or forever with ttlMs: null, and a second
requireInput replaced the first wait so the first never settled. Reject the
pending wait when the task settles, refuse a second concurrent wait, and
drop the abort listener once a wait resolves.
- TasksExtension goes in McpServerOptions.extensions; ServerOptions has no
  extensions option.
- The requester half ships in this PR as TasksClientExtension from
  @modelcontextprotocol/client/ext/tasks, not @modelcontextprotocol/ext-tasks.
- The server example fired the work with void and no catch; requireInput
  rejects on cancel or purge, so that crashed Node with an unhandled
  rejection. Settle failures on the task instead, here and in the TSDoc.
- The schema header pointed at a vendored test fixture that does not exist.
The client guide answers input_required inside an async onUpdate, but
waitFor called it without awaiting. Polling went on at the task's interval
while the user was being asked, so the same unanswered input request came
back and was asked again on every poll, and a rejection from the callback
was unhandled. Await the callback before the next poll and let its
rejection reject waitFor.
@modelcontextprotocol/core-internal is private, so users cannot import the
wire types from it; they come from the server and client ext/tasks subpaths.
…6-07-28 only

The task principal was the OAuth client id, so every user of a shared or
public client could read, answer and cancel the others' tasks. The default
is now the client id plus the token subject at authInfo.extra.sub when the
verifier sets one, and TasksExtensionOptions.principal picks any identity.

On 2025-11-25 the capability was advertised, then every tasks call failed
with -32021 asking for an envelope that era cannot carry, and the core
legacy tasks/get and tasks/cancel got the extension's handlers. The
extension's methods now answer -32601 there, and tasks.create refuses with a
-32021 that names the era.
everythingServer now installs TasksExtension over one in-memory store shared
by the per-request servers, and registers the tools the tasks-* scenarios
call by name: greet, slow_compute, failing_job, protocol_error_job,
confirm_delete, multi_input and test_tool_with_task. All nine tasks-*
server scenarios pass, so they leave the expected-failures baseline.
…ndles

- tasks/update acked a request whose inputResponses the protocol dropped as
  not bare results, or that had none, leaving the task waiting. It now
  answers -32602 naming the refused keys, or the missing field; an empty
  object is still a valid partial update.
- The tools/call middleware refused a task handle minted outside create
  after the task was already running, so the task leaked until its TTL, or
  forever with ttlMs: null. It now cancels the task before refusing.
TTL expiry and close() aborted the same signal as tasks/cancel with no
reason, and a pending requireInput rejected with "was cancelled" in every
case. The signal now carries an Error naming cancellation, expiry or store
close, and the wait rejects with it.
…-type headers

The TasksClientExtension example built a client on the default legacy
handshake, where tasks.callTool is refused with -32021. It now negotiates,
and the header says the extension needs a 2026-07-28 connection. The
wire-type and schema headers keep provenance only.
…ol/core/ext/tasks

The Tasks schemas, types and constants lived in the private core-internal,
so code implementing either side without the SDK's server or client had no
published import, and the changeset had pointed at a private package. They
now live in core/ext/tasks, like core/ext/skills: the zod schemas and
constants move unchanged, and the types are inferred from the schemas, so
there is one definition. core-internal/ext/tasks is gone.

The core types describe inputRequests structurally ({ method, params }), as
core cannot import the SDK's MRTR unions. The server and client subpaths
re-export core's definitions, plus the precise InputRequest(s) and
InputResponse(s) types that requireInput and update take.


Every export of server/ext/tasks, client/ext/tasks and core/ext/tasks, and
each subpath's module doc, says it may change in a minor release while the
extensions SEPs settle; so do the guides and the changeset.
…RPC error

The spec says a server MUST answer a request that needs an undeclared client
capability with MissingRequiredClientCapabilityError (-32021) carrying
requiredCapabilities. McpServer wrapped it as an isError tool result, like any
other throw; it now passes it through, as it does UrlElicitationRequiredError.
…docs say what a tool can propagate

docs/servers/errors.md said the SDK converts anything a tool throws and that
UrlElicitationRequiredError is the only error a tool can propagate.
…nt ids

They ran on one transport inside packages/server, which needed a dev
dependency on the client and four tsconfig paths. They are now tasks:* and
typescript:tasks:* requirements, with new cases for an outputSchema tool, the
input-request capability check and tasks/update answer validation.
…l answer with a task

- A task may only request input the creating request's client capabilities
  cover: tasks.create records them and InMemoryTaskStore.requireInput rejects
  a request that needs more, as the in-band input_required gate does.
- InMemoryTaskStore.update validates each answer against the request it
  answers and refuses a bad one with -32602, keeping nothing from that update.
- McpServer skips outputSchema validation for a result of another kind, such
  as a task handle; before, the client got an isError result and the work ran
  on unseen.
- tasks.create's refusal no longer names tools/call as the tool.
- Docs and changeset: tasks.callTool's limits, and that task access is by
  principal, not by scope.
…nd client subpaths

Nothing in the SDK used them, and the three result schemas require a
resultType that client.request strips before a caller's schema runs. They stay
in core/ext/tasks, as the Skills subpaths do it.
@mattzcarey
mattzcarey force-pushed the feat/pluggable-task-workflow branch from b9b2ddf to f54eff4 Compare November 19, 2026 00:59

@claude claude Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No new blocking issues. 3 optional suggestions (nits or notes on pre-existing code) were found and not posted.

2025-11-25 does not define the code, so there the tool error stays as it was,
the way the -32042 passthrough is gated to its own era. errors.md says which
era each exception applies to.

@claude claude Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nothing blocking. The comments below are optional suggestions. There is no need to push a fix for them before merging.

3 other optional suggestions (nits or notes on pre-existing code) were found and not posted.

Comment thread test/e2e/requirements.ts Resolved

@claude claude Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No new blocking issues. 4 optional suggestions (nits or notes on pre-existing code) were found and not posted. Nothing in this review needs a push before merging.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

v2 Ideas, requests and plans for v2 of the SDK which will incorporate major changes and fixes

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant