You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/specification/draft/basic/utilities/tasks.mdx
+20-20Lines changed: 20 additions & 20 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -9,17 +9,17 @@ title: Tasks
9
9
<Note>
10
10
11
11
Tasks are newly-introduced in this version of the MCP specification and are currently considered **experimental**.
12
-
The design of tasks may evolve in future protocol versions.
12
+
The design and behavior of tasks may evolve in future protocol versions.
13
13
14
14
</Note>
15
15
16
16
The Model Context Protocol (MCP) allows requestors (which can be either clients or servers, depending on the direction of communication) to augment their requests with **tasks**. Tasks are durable state machines that carry information about the underlying execution state of the request they wrap, and are intended for requestor polling and deferred result retrieval. Each task is uniquely identifiable by a receiver-generated **task ID**.
17
17
18
18
## User Interaction Model
19
19
20
-
Tasks are designed to be **application-driven**—receivers tightly-control which requests (if any) support task-based execution and manage the lifecycles of those tasks; meanwhile, requestors own the responsibility for augmenting requests with tasks, and for polling on the results of those tasks.
20
+
Tasks are designed to be **application-driven** - receivers tightlycontrol which requests (if any) support task-based execution and manage the lifecycles of those tasks; meanwhile, requestors are responsible for augmenting requests with tasks and for polling for the results of those tasks.
21
21
22
-
Implementations are free to expose tasks through any interface pattern that suits their needs—the protocol itself does not mandate any specific user interaction model.
22
+
Implementations are free to expose tasks through any interface pattern that suits their needs — the protocol itself does not mandate any specific user interaction model.
23
23
24
24
## Capabilities
25
25
@@ -142,7 +142,7 @@ To create a task, requestors send a request with the `task` field included in th
142
142
}
143
143
```
144
144
145
-
When a receiver accepts a task-augmented request, it returns a `CreateTaskResult` containing task metadata. This response does not include the actual operation result. The actual result (e.g., tool result for `tools/call`) becomes available only through `tasks/result` after the task completes.
145
+
When a receiver accepts a task-augmented request, it returns a `CreateTaskResult` containing task metadata. The response does not include the actual operation result. The actual result (e.g., tool result for `tools/call`) becomes available only through `tasks/result` after the task completes.
146
146
147
147
<Note>
148
148
@@ -151,13 +151,13 @@ When a task is created in response to a `tools/call` request, host applications
151
151
To support this pattern, servers can provide an optional `io.modelcontextprotocol/model-immediate-response` key in the `_meta` field of the `CreateTaskResult`. The value of this key should be a string intended to be passed as an immediate tool result to the model.
152
152
If a server does not provide this field, the host application can fall back to its own predefined message.
153
153
154
-
This guidance is non-binding, and is provisional logic intended to account for this use case. This may be formalized as part of `CreateTaskResult` in future protocol versions.
154
+
This guidance is non-binding and is provisional logic intended to account for the specific use case. This behavior may be formalized or modified as part of `CreateTaskResult` in future protocol versions.
155
155
156
156
</Note>
157
157
158
158
### Getting Tasks
159
159
160
-
To retrieve the state of a task, requestors send a `tasks/get` request:
160
+
To retrieve the state of a task, requestors can send a `tasks/get` request:
161
161
162
162
**Request:**
163
163
@@ -191,9 +191,9 @@ To retrieve the state of a task, requestors send a `tasks/get` request:
191
191
192
192
### Retrieving Task Results
193
193
194
-
After a task completes, the actual operation result is retrieved via `tasks/result`. This is distinct from the initial `CreateTaskResult` response, which contains only task metadata. The result structure matches the original request type (e.g., `CallToolResult` for `tools/call`).
194
+
After a task completes the operation result is retrieved via `tasks/result`. This is distinct from the initial `CreateTaskResult` response, which contains only task metadata. The result structure matches the original request type (e.g., `CallToolResult` for `tools/call`).
195
195
196
-
To retrieve the result of a completed task, requestors send a `tasks/result` request:
196
+
To retrieve the result of a completed task, requestors can send a `tasks/result` request:
197
197
198
198
**Request:**
199
199
@@ -233,7 +233,7 @@ To retrieve the result of a completed task, requestors send a `tasks/result` req
233
233
234
234
### Task Status Notification
235
235
236
-
When a task's status changes, receivers **MAY** send a `notifications/tasks/status` notification to inform the requestor of the change. This notification includes the full task state.
236
+
When a task status changes, receivers **MAY** send a `notifications/tasks/status` notification to inform the requestor of the change. This notification includes the full task state.
237
237
238
238
**Notification:**
239
239
@@ -257,7 +257,7 @@ Requestors **MUST NOT** rely on receiving this notifications, as it is optional.
257
257
258
258
### Listing Tasks
259
259
260
-
To retrieve a list of tasks, requestors send a `tasks/list` request. This operation supports pagination.
260
+
To retrieve a list of tasks, requestors can send a `tasks/list` request. This operation supports pagination.
261
261
262
262
**Request:**
263
263
@@ -301,7 +301,7 @@ To retrieve a list of tasks, requestors send a `tasks/list` request. This operat
301
301
302
302
### Cancelling Tasks
303
303
304
-
To explicitly cancel a task, requestors send a `tasks/cancel` request.
304
+
To explicitly cancel a task, requestors can send a `tasks/cancel` request.
305
305
306
306
**Request:**
307
307
@@ -340,21 +340,21 @@ These requirements apply to all parties that support receiving task-augmented re
340
340
### Task Support and Handling
341
341
342
342
1. Receivers that do not declare the task capability for a request type **MUST** process requests of that type normally, ignoring any task-augmentation metadata if present.
343
-
1. Receivers that do declare the task capability for a request type **MAY** return an error for non-task-augmented requests of that type, requiring requestors to use task augmentation.
343
+
1. Receivers that declare the task capability for a request type **MAY** return an error for non-task-augmented requests, requiring requestors to use task augmentation.
344
344
345
345
### Task ID Requirements
346
346
347
347
1. Task IDs **MUST** be a string value.
348
348
1. Task IDs **MUST** be generated by the receiver when creating a task.
349
-
1. Task IDs **MUST** be unique across all tasks controlled by the receiver.
349
+
1. Task IDs **MUST** be unique among all tasks controlled by the receiver.
350
350
351
351
### Task Status Lifecycle
352
352
353
353
1. Tasks **MUST** begin in the `working` status when created.
354
354
1. Receivers **MUST** only transition tasks through the following valid paths:
355
355
1. From `working`: may move to `input_required`, `completed`, `failed`, or `cancelled`
356
356
1. From `input_required`: may move to `working`, `completed`, `failed`, or `cancelled`
357
-
1. Tasks in `completed`, `failed`, or `cancelled` status **MUST NOT** transition to any other status (terminal states)
357
+
1. Tasks with a `completed`, `failed`, or `cancelled` status are in a terminal state and **MUST NOT** transition to any other status
358
358
359
359
**Task Status State Diagram:**
360
360
@@ -382,7 +382,7 @@ stateDiagram-v2
382
382
383
383
<Note>
384
384
385
-
In the Streamable HTTP (SSE) transport, it is common for servers to close SSE streams upon sending a response message, rendering the stream that task messages will be sent on ambiguous.
385
+
With the Streamable HTTP (SSE) transport, servers often close SSE streams after delivering a response message, which can lead to ambiguity regarding the stream used for subsequent task messages.
386
386
387
387
Implementations have flexibility in how they manage SSE streams during task polling and result retrieval.
388
388
One possible approach is maintaining an SSE stream on `tasks/result` (see notes on the `input_required` status).
@@ -394,15 +394,15 @@ While this note is not prescriptive regarding the specific usage of SSE streams,
394
394
395
395
1. When the task receiver has messages for the requestor that are necessary to complete the task, the receiver **SHOULD** move the task to the `input_required` status.
396
396
1. The receiver **MUST** include the `io.modelcontextprotocol/related-task` metadata in the request to associate it with the task.
397
-
1. When the requestor encounters the `input_required` status, it **SHOULD** call `tasks/result` prematurely.
397
+
1. When the requestor encounters the `input_required` status, it **SHOULD**preemptively call `tasks/result`.
398
398
1. When the receiver receives all required input, the task **SHOULD** transition out of `input_required` status (typically back to `working`).
399
399
400
400
### TTL and Resource Management
401
401
402
402
1. Receivers **MUST** include a `createdAt` timestamp (ISO 8601 format) in all task responses to indicate when the task was created.
403
403
1. Receivers **MAY** override the requested `ttl` duration.
404
404
1. Receivers **MUST** include the actual `ttl` duration (or `null` for unlimited) in `tasks/get` responses.
405
-
1. After a task's `ttl`duration has elapsed from creation, receivers **MAY** delete the task and its results, regardless of the task's status.
405
+
1. After a task's `ttl`lifetime has elapsed, receivers **MAY** delete the task and its results, regardless of the task status.
406
406
1. Receivers **MAY** include a `pollInterval` value (in milliseconds) in `tasks/get` responses to suggest polling intervals. Requestors **SHOULD** respect this value when provided.
407
407
408
408
### Result Retrieval
@@ -414,7 +414,7 @@ While this note is not prescriptive regarding the specific usage of SSE streams,
414
414
415
415
### Associating Task-Related Messages
416
416
417
-
1. All requests, notifications, and responses related to a task **MUST** include the `io.modelcontextprotocol/related-task` key in their `_meta`, with the value set to an object with a `taskId` matching the associated task ID.
417
+
1. All requests, notifications, and responses related to a task **MUST** include the `io.modelcontextprotocol/related-task` key in their `_meta` field, with the value set to an object with a `taskId` matching the associated task ID.
418
418
1. For example, an elicitation that a task-augmented tool call depends on **MUST** share the same related task ID with that tool call's task.
419
419
1. For the `tasks/get`, `tasks/list`, `tasks/result`, and `tasks/cancel` operations, the `taskId` parameter in the request **MUST** be used as the source of truth for identifying the target task. Requestors **SHOULD NOT** include `io.modelcontextprotocol/related-task` metadata in these requests, and receivers **MUST** ignore such metadata if present in favor of the RPC method parameter.
420
420
Similarly, for the `tasks/get`, `tasks/list`, and `tasks/cancel` operations, receivers **SHOULD NOT** include `io.modelcontextprotocol/related-task` metadata in the result messages, as the `taskId` is already present in the response structure.
@@ -427,7 +427,7 @@ While this note is not prescriptive regarding the specific usage of SSE streams,
427
427
428
428
### Task Progress Notifications
429
429
430
-
Task-augmented requests support progress notifications as defined in the [progress](./progress) specification. The `progressToken` provided in the initial request remains valid throughout the task's lifetime.
430
+
Task-augmented requests support progress notifications as defined in the [progress](./progress) specification. The `progressToken` provided in the initial request remains valid throughout the task lifetime.
431
431
432
432
### Task Listing
433
433
@@ -441,7 +441,7 @@ Task-augmented requests support progress notifications as defined in the [progre
441
441
1. Receivers **MUST** reject cancellation requests for tasks already in a terminal status (`completed`, `failed`, or `cancelled`) with error code `-32602` (Invalid params).
442
442
1. Upon receiving a valid cancellation request, receivers **SHOULD** attempt to stop the task's execution (best effort) and **MUST** transition the task to `cancelled` status before sending the response.
443
443
1. Once a task is cancelled, it **MUST** remain in `cancelled` status even if execution continues to completion or fails.
444
-
1. The `tasks/cancel` operation does not define deletion behavior. However, receivers **MAY** delete cancelled tasks at their discretion at any time, including immediately after cancellation or after the task's`ttl` expires.
444
+
1. The `tasks/cancel` operation does not define deletion behavior. However, receivers **MAY** delete cancelled tasks at their discretion at any time, including immediately after cancellation or after the task `ttl` expires.
445
445
1. Requestors **SHOULD NOT** rely on cancelled tasks being retained for any specific duration and should retrieve any needed information before cancelling.
0 commit comments