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
+40-5Lines changed: 40 additions & 5 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -85,6 +85,11 @@ This is to be interpreted as a fine-grained layer in addition to capabilities. I
85
85
86
86
### Creating Tasks
87
87
88
+
Task-augmented requests follow a two-phase response pattern that differs from normal requests:
89
+
90
+
-**Normal requests**: The server processes the request and returns the actual operation result directly.
91
+
-**Task-augmented requests**: The server accepts the request and immediately returns a `CreateTaskResult` containing task metadata. The actual operation result becomes available later through `tasks/result` after the task completes.
92
+
88
93
To create a task, requestors send a request with the `modelcontextprotocol.io/task` key included in `_meta`, with a `taskId` value representing the task ID. Requestors **MAY** include a `keepAlive`, with a value representing how long after completion the requestor would like the task results to be kept for.
89
94
90
95
**Request:**
@@ -93,8 +98,12 @@ To create a task, requestors send a request with the `modelcontextprotocol.io/ta
93
98
{
94
99
"jsonrpc": "2.0",
95
100
"id": 1,
96
-
"method": "some_method",
101
+
"method": "tools/call",
97
102
"params": {
103
+
"name": "get_weather",
104
+
"arguments": {
105
+
"city": "New York"
106
+
},
98
107
"_meta": {
99
108
"modelcontextprotocol.io/task": {
100
109
"taskId": "786512e2-9e0d-44bd-8f29-789f320fe840",
@@ -105,6 +114,28 @@ To create a task, requestors send a request with the `modelcontextprotocol.io/ta
105
114
}
106
115
```
107
116
117
+
**Response:**
118
+
119
+
```json
120
+
{
121
+
"jsonrpc": "2.0",
122
+
"id": 1,
123
+
"result": {
124
+
"taskId": "786512e2-9e0d-44bd-8f29-789f320fe840",
125
+
"status": "submitted",
126
+
"keepAlive": 60000,
127
+
"pollInterval": 5000,
128
+
"_meta": {
129
+
"modelcontextprotocol.io/related-task": {
130
+
"taskId": "786512e2-9e0d-44bd-8f29-789f320fe840"
131
+
}
132
+
}
133
+
}
134
+
}
135
+
```
136
+
137
+
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.
138
+
108
139
### Getting Tasks
109
140
110
141
To retrieve the state of a task, requestors send a `tasks/get` request:
@@ -144,6 +175,8 @@ To retrieve the state of a task, requestors send a `tasks/get` request:
144
175
145
176
### Retrieving Task Results
146
177
178
+
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`).
179
+
147
180
To retrieve the result of a completed task, requestors send a `tasks/result` request:
148
181
149
182
**Request:**
@@ -381,7 +414,8 @@ stateDiagram-v2
381
414
382
415
### Result Retrieval
383
416
384
-
1. Receivers **MUST** only return results from `tasks/result` when the task status is `completed`.
417
+
1. Receivers that accept a task-augmented request **MUST** return a `CreateTaskResult` as the response. This result **SHOULD** be returned as soon as possible after accepting the task.
418
+
1. Receivers **MUST** only return the actual operation results via `tasks/result` when the task status is `completed`.
385
419
1. Receivers **MUST** return an error if `tasks/result` is called for a task in any other status.
386
420
1. Requestors **MAY** call `tasks/result` multiple times for the same task while it remains available.
387
421
@@ -424,8 +458,8 @@ sequenceDiagram
424
458
participant S as Server (Receiver)
425
459
Note over C,S: 1. Task Creation
426
460
C->>S: Request with task metadata (taskId, keepAlive)
0 commit comments