Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
90 commits
Select commit Hold shift + click to select a range
08116ac
Write specification for SEP-1686: Tasks
LucaButBoring Oct 29, 2025
74ba344
Write schema for task-related types
LucaButBoring Oct 29, 2025
d52881b
Add a mention of tasks to the Primitives docs
LucaButBoring Oct 29, 2025
6444eb3
Make task idempotency a MAY instead of a MUST
LucaButBoring Oct 31, 2025
42a4e5b
Add consistency requirement that tasks/list reflect tasks/get
LucaButBoring Oct 31, 2025
1a4e205
Add capabilities and annotations for tasks
LucaButBoring Oct 31, 2025
cd7c4cd
Commit updated schema
LucaButBoring Oct 31, 2025
726a4db
Add tasks/delete operation
LucaButBoring Oct 31, 2025
7585a33
Move task-augmentation capabilities under tasks.requests for clarity
LucaButBoring Oct 31, 2025
bb707b1
Merge branch 'main' into feat/tasks
LucaButBoring Oct 31, 2025
a0b93c8
Clarify that failed status refers to lifecycle
LucaButBoring Oct 31, 2025
81fd957
Specify that task methods themselves should not have related-task met…
LucaButBoring Oct 31, 2025
c0260cc
Rename pollFrequency to pollInterval
LucaButBoring Oct 31, 2025
5e53553
Document input_required status in data types
LucaButBoring Nov 4, 2025
e4e2a08
Add capability for augmenting tasks/delete itself with a task
LucaButBoring Nov 6, 2025
2a9c374
Receiver SHOULD move tasks to input_required
LucaButBoring Nov 6, 2025
458571f
Merge branch 'main' of https://github.com/modelcontextprotocol/modelc…
LucaButBoring Nov 6, 2025
e57ea31
Fix input_required and failed status descriptions
LucaButBoring Nov 6, 2025
97fcd60
Add optional status notifications for tasks
LucaButBoring Nov 6, 2025
2b9c6da
Format docs
LucaButBoring Nov 6, 2025
9b717e2
Make "failed" reflect the request error
LucaButBoring Nov 7, 2025
6abc9bb
Merge branch 'main' into feat/tasks
LucaButBoring Nov 7, 2025
96b8d49
Fix empty result type
LucaButBoring Nov 7, 2025
0394a5d
Restrict tasks to tools/call, elicitation/create, and sampling/create…
LucaButBoring Nov 7, 2025
f7229a5
Add capabilities for tasks/list and tasks/delete
LucaButBoring Nov 7, 2025
0ab6785
Use response instead of notification for task acceptance
LucaButBoring Nov 7, 2025
2fdea38
Make task IDs exclusively server-generated
LucaButBoring Nov 7, 2025
e96ce21
Add stipulation that receivers are allowed to require tasks
LucaButBoring Nov 7, 2025
642c3c7
Update tasks/result to block until completion
LucaButBoring Nov 7, 2025
7d008e0
Add explicit note that tasks/result can return an error
LucaButBoring Nov 7, 2025
d05cfbb
Alter input_required to note tasks/result relation
LucaButBoring Nov 8, 2025
dbc2b0a
Remove submitted and unknown statuses
LucaButBoring Nov 8, 2025
8169347
Update cancellation to reflect CreateTaskResult semantics
LucaButBoring Nov 8, 2025
8a675ea
Update progress spec to reflect task semantics
LucaButBoring Nov 8, 2025
43f9cf4
Merge branch 'main' into feat/tasks
LucaButBoring Nov 8, 2025
33c3215
Merge branch 'main' into feat/tasks
LucaButBoring Nov 10, 2025
13c6835
Add optional statusMessage field
LucaButBoring Nov 10, 2025
b9a9ac4
Remove cancellation changes and convert deletion into cancel RPC method
LucaButBoring Nov 10, 2025
aa0629a
Replace keepalive with TTL; add createdAt
LucaButBoring Nov 11, 2025
7421af3
Merge branch 'main' into feat/tasks
LucaButBoring Nov 11, 2025
b9e04ad
Make CancelTaskResult include full task; loosen deletion reqs
LucaButBoring Nov 11, 2025
6bcfab5
Rewrite access control section to explain session-binding
LucaButBoring Nov 11, 2025
29fffbc
Make notifications include full task info
LucaButBoring Nov 11, 2025
bc12768
Add experimental notice
LucaButBoring Nov 11, 2025
b25069f
Link to task spec from progress
LucaButBoring Nov 11, 2025
ca166f3
Update task capabilities in lifecycle spec example
LucaButBoring Nov 11, 2025
fb7d063
Update changelog to include tasks
LucaButBoring Nov 11, 2025
5cafa6d
Link to Progress spec from Tasks spec
LucaButBoring Nov 11, 2025
4dbb5c7
Add note about SSE stream management
LucaButBoring Nov 11, 2025
7da2b7f
Add note on metadata for immediate model responses
LucaButBoring Nov 12, 2025
66b9872
Switch to reverse-DNS metadata prefixes
LucaButBoring Nov 12, 2025
a4f8c07
Revise immediate result note to clarify non-binding nature
LucaButBoring Nov 12, 2025
60620cd
Fix minor issues
LucaButBoring Nov 12, 2025
e3dce0d
Clarify distinction between statusMessage and error fields
LucaButBoring Nov 12, 2025
11bc887
Fix task capabilities in lifecycle docs again
LucaButBoring Nov 12, 2025
68c0d63
Adjust cancellation spec to link to tasks spec for task cancellation
LucaButBoring Nov 12, 2025
544c376
Remove related-task from responses that include the task ID already
LucaButBoring Nov 12, 2025
4736c2e
Merge branch 'main' of https://github.com/modelcontextprotocol/modelc…
LucaButBoring Nov 12, 2025
3c7e9e4
Remove notifications/tasks/created
LucaButBoring Nov 12, 2025
07a3a32
Move task parameters to dedicated field
LucaButBoring Nov 12, 2025
aa79e44
Remove _meta from CreateTaskResult
LucaButBoring Nov 13, 2025
9e5d23b
Clarify taskHint behavior
LucaButBoring Nov 13, 2025
4508eb2
Update SSE recommendation for tasks in sHTTP
LucaButBoring Nov 13, 2025
581d60c
Merge branch 'main' of https://github.com/modelcontextprotocol/modelc…
LucaButBoring Nov 13, 2025
6c315d9
Merge branch 'main' into feat/tasks
LucaButBoring Nov 14, 2025
3b3c583
Nest data inside of CreateTaskResult.task
LucaButBoring Nov 14, 2025
f9e4479
Merge branch 'main' of https://github.com/modelcontextprotocol/modelc…
LucaButBoring Nov 14, 2025
29a1971
Apply grammatical fixes to tasks spec
LucaButBoring Nov 14, 2025
b0cb349
Add definitions section and fix grammar
LucaButBoring Nov 14, 2025
b94efec
Add capability tables for tasks
LucaButBoring Nov 14, 2025
00566e2
Change taskHint to enum
LucaButBoring Nov 14, 2025
93afbca
Specify taskHint values in spec
LucaButBoring Nov 14, 2025
5ede2d9
Apply suggestions from code review
LucaButBoring Nov 14, 2025
4776955
Link to RFC 3339 instead of Wikipedia for ISO 8601
LucaButBoring Nov 14, 2025
861e4b8
Mark tasks as experimental in architecture docs
LucaButBoring Nov 14, 2025
a888e22
Application-driven -> requestor-driven
LucaButBoring Nov 14, 2025
7ab865a
Fix inconsistency in task capabilities spec
LucaButBoring Nov 14, 2025
a3a6be4
Clarify task TTL definition
LucaButBoring Nov 14, 2025
2943683
Minor task fixes
LucaButBoring Nov 14, 2025
b8ba4d5
Apply security changes from code review
LucaButBoring Nov 14, 2025
f104558
Remove session mentions in favor of auth
LucaButBoring Nov 14, 2025
fad5644
Remove `error` field in favor of `statusMessage`
LucaButBoring Nov 14, 2025
e397f5d
Clarify task polling under "Getting Tasks"
LucaButBoring Nov 14, 2025
7604c82
Add a line explaining requestor-driven tasks
LucaButBoring Nov 14, 2025
87e8d42
Add line on task use cases to spec
LucaButBoring Nov 14, 2025
0f8aeb8
Merge branch 'main' into feat/tasks
LucaButBoring Nov 14, 2025
f41e5e3
Apply suggestions from code review
LucaButBoring Nov 14, 2025
43113ab
Add missing link
LucaButBoring Nov 14, 2025
ba39ed7
Add missing link
LucaButBoring Nov 14, 2025
cbf3dca
Relax task augmentation with capabilities to "SHOULD", fix "task meta…
LucaButBoring Nov 14, 2025
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
3 changes: 2 additions & 1 deletion docs/docs.json
Original file line number Diff line number Diff line change
Expand Up @@ -231,7 +231,8 @@
"pages": [
"specification/draft/basic/utilities/cancellation",
"specification/draft/basic/utilities/ping",
"specification/draft/basic/utilities/progress"
"specification/draft/basic/utilities/progress",
"specification/draft/basic/utilities/tasks"
]
}
]
Expand Down
4 changes: 4 additions & 0 deletions docs/docs/learn/architecture.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -132,6 +132,10 @@ MCP also defines primitives that _clients_ can expose. These primitives allow MC

For more details about client primitives see [client concepts](./client-concepts).

Besides server and client primitives, the protocol offers cross-cutting utility primitives that augment how requests are executed:

- **Tasks (Experimental)**: Durable execution wrappers that enable deferred result retrieval and status tracking for MCP requests (e.g., expensive computations, workflow automation, batch processing, multi-step operations)
Copy link
Member

Choose a reason for hiding this comment

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

I'd be curious to better understand the meaning of the term "experimental" here. Does it suggest that the feature is subject to breaking revisions in the future? Should SDK implementers accordingly annotate all APIs touching task functionality as experimental?

Copy link
Member

Choose a reason for hiding this comment

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

Copy link
Member

Choose a reason for hiding this comment

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

@eiriktsarpalis Not sure how that clears up the meaning of "experimental" with regard to future breaking changes and necessity of SDK annotations. The line you linked to says:

Tasks are useful for representing expensive computations and batch processing requests, and integrate seamlessly with external job APIs.

Copy link
Member

@eiriktsarpalis eiriktsarpalis Nov 21, 2025

Choose a reason for hiding this comment

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

Not sure how that happened, I meant to link to this line: https://github.com/modelcontextprotocol/modelcontextprotocol/pull/1732/files#diff-ce54e98f0e555c404f17c1180c4a65e774b0ed0ad71e207410030cf08356cf73R12

Tasks were introduced in version 2025-11-25 of the MCP specification and are currently considered experimental.
The design and behavior of tasks may evolve in future protocol versions.

Copy link
Contributor

Choose a reason for hiding this comment

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

Which means adding more features and SubTask support.

Copy link
Member

Choose a reason for hiding this comment

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

Maybe so, but if those additions are meant to be incremental I'm not sure why we'd want to qualify the feature as experimental.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

The evolutions may not be purely incremental, but we'll see.

The request to mark this as experimental came out of the Core Maintainer reviews, and it's largely because we wanted to get this out in its current form for people to start building on, so we could get real, not-toy feedback on it in the coming months. We had been facing a chicken-and-egg problem over the past several months of discussions between getting this finalized and having people actually trial it in applications (huge thanks to @evalstate for being one of the few willing and able to, btw), which was something the Core Maintainers wanted to see to have confidence that this was definitely the right solution across the board.

I think that in particular, we want to avoid a situation like we have with structuredOutput, where there have been divergences between implementations in SDKs and applications that have led to spotty support that isn't easy to resolve anymore. Releasing this in the upcoming spec release with an experimental label was the way we agreed to signpost the possibility of changing it in upcoming releases -- while simultaneously having enough "officiality" to get it into SDKs, so that people can actually build on it. That will give us a very high degree of confidence that the current core design is as good as it can be (short of net-new additions on top of it) and we can remove the experimental label.

Simultaneously, I don't expect much to actually change in the core design, however. Consider it hedging, since this is such a large addition to MCP 😄

Copy link
Contributor

Choose a reason for hiding this comment

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

First of all, thank you all very much for your contributions. I'm currently developing a version (for Alibaba), and we also have similar requirements. Internally, we use various methods such as SSE, RocketMQ's litetopic, and asynchronous webhooks to achieve this. Within the company's network environment, we can also notify clients through other means. We've conducted some internal reviews based on this, and I think the current design is quite complete, at least it standardizes end-to-end behavior quite well.

While I don't know the actual implementation in your work, it will definitely involve databases and persistent message queue components to ensure the traceability of the entire task's state transition. For example, in our scenario, a heavy task might, after completion, notify our Agents system, allowing us to restart our agents either locally or on a different machine to continue processing.

I hope to deliver a version based on this first, thereby resolving internal interoperability issues. Deliver value first, then discuss improvements.


#### Notifications

The protocol supports real-time notifications to enable dynamic updates between servers and clients. For example, when a server's available tools change—such as when new functionality becomes available or existing tools are modified—the server can send tool update notifications to inform connected clients about these changes. Notifications are sent as JSON-RPC 2.0 notification messages (without expecting a response) and enable MCP servers to provide real-time updates to connected clients.
Expand Down
45 changes: 33 additions & 12 deletions docs/specification/draft/basic/lifecycle.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -67,6 +67,16 @@ The client **MUST** initiate this phase by sending an `initialize` request conta
"elicitation": {
"form": {},
"url": {}
},
"tasks": {
"requests": {
"elicitation": {
"create": {}
},
"sampling": {
"createMessage": {}
}
}
}
},
"clientInfo": {
Expand Down Expand Up @@ -105,6 +115,15 @@ The server **MUST** respond with its own capabilities and information:
},
"tools": {
"listChanged": true
},
"tasks": {
"list": {},
"cancel": {},
"requests": {
"tools": {
"call": {}
}
}
}
},
"serverInfo": {
Expand Down Expand Up @@ -169,18 +188,20 @@ available during the session.

Key capabilities include:

| Category | Capability | Description |
| -------- | -------------- | ------------------------------------------------------------------------------------ |
| Client | `roots` | Ability to provide filesystem [roots](/specification/draft/client/roots) |
| Client | `sampling` | Support for LLM [sampling](/specification/draft/client/sampling) requests |
| Client | `elicitation` | Support for server [elicitation](/specification/draft/client/elicitation) requests |
| Client | `experimental` | Describes support for non-standard experimental features |
| Server | `prompts` | Offers [prompt templates](/specification/draft/server/prompts) |
| Server | `resources` | Provides readable [resources](/specification/draft/server/resources) |
| Server | `tools` | Exposes callable [tools](/specification/draft/server/tools) |
| Server | `logging` | Emits structured [log messages](/specification/draft/server/utilities/logging) |
| Server | `completions` | Supports argument [autocompletion](/specification/draft/server/utilities/completion) |
| Server | `experimental` | Describes support for non-standard experimental features |
| Category | Capability | Description |
| -------- | -------------- | ---------------------------------------------------------------------------------------- |
| Client | `roots` | Ability to provide filesystem [roots](/specification/draft/client/roots) |
| Client | `sampling` | Support for LLM [sampling](/specification/draft/client/sampling) requests |
| Client | `elicitation` | Support for server [elicitation](/specification/draft/client/elicitation) requests |
| Client | `tasks` | Support for [task-augmented](/specification/draft/basic/utilities/tasks) client requests |
| Client | `experimental` | Describes support for non-standard experimental features |
| Server | `prompts` | Offers [prompt templates](/specification/draft/server/prompts) |
| Server | `resources` | Provides readable [resources](/specification/draft/server/resources) |
| Server | `tools` | Exposes callable [tools](/specification/draft/server/tools) |
| Server | `logging` | Emits structured [log messages](/specification/draft/server/utilities/logging) |
| Server | `completions` | Supports argument [autocompletion](/specification/draft/server/utilities/completion) |
| Server | `tasks` | Support for [task-augmented](/specification/draft/basic/utilities/tasks) server requests |
| Server | `experimental` | Describes support for non-standard experimental features |

Capability objects can describe sub-capabilities like:

Expand Down
9 changes: 5 additions & 4 deletions docs/specification/draft/basic/utilities/cancellation.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -34,16 +34,17 @@ notification containing:
1. Cancellation notifications **MUST** only reference requests that:
- Were previously issued in the same direction
- Are believed to still be in-progress
2. The `initialize` request **MUST NOT** be cancelled by clients
3. Receivers of cancellation notifications **SHOULD**:
1. The `initialize` request **MUST NOT** be cancelled by clients
1. For [task-augmented requests](./tasks), the `tasks/cancel` request **MUST** be used instead of the `notifications/cancelled` notification. Tasks have their own dedicated cancellation mechanism that returns the final task state.
1. Receivers of cancellation notifications **SHOULD**:
- Stop processing the cancelled request
- Free associated resources
- Not send a response for the cancelled request
4. Receivers **MAY** ignore cancellation notifications if:
1. Receivers **MAY** ignore cancellation notifications if:
- The referenced request is unknown
- Processing has already completed
- The request cannot be cancelled
5. The sender of the cancellation notification **SHOULD** ignore any response to the
1. The sender of the cancellation notification **SHOULD** ignore any response to the
request that arrives afterward

## Timing Considerations
Expand Down
4 changes: 4 additions & 0 deletions docs/specification/draft/basic/utilities/progress.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -68,6 +68,10 @@ The receiver **MAY** then send progress notifications containing:
- Send notifications at whatever frequency they deem appropriate
- Omit the total value if unknown

3. For [task-augmented requests](./tasks), the `progressToken` provided in the original request **MUST** continue to be used for progress notifications throughout the task's lifetime, even after the `CreateTaskResult` has been returned. The progress token remains valid and associated with the task until the task reaches a terminal status.
- Progress notifications for tasks **MUST** use the same `progressToken` that was provided in the initial task-augmented request
- Progress notifications for tasks **MUST** stop after the task reaches a terminal status (`completed`, `failed`, or `cancelled`)

```mermaid
sequenceDiagram
participant Sender
Expand Down
Loading