Skip to content

Commit 0ab6785

Browse files
committed
Use response instead of notification for task acceptance
1 parent f7229a5 commit 0ab6785

File tree

4 files changed

+134
-58
lines changed

4 files changed

+134
-58
lines changed

docs/specification/draft/basic/utilities/tasks.mdx

Lines changed: 40 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -85,6 +85,11 @@ This is to be interpreted as a fine-grained layer in addition to capabilities. I
8585

8686
### Creating Tasks
8787

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+
8893
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.
8994

9095
**Request:**
@@ -93,8 +98,12 @@ To create a task, requestors send a request with the `modelcontextprotocol.io/ta
9398
{
9499
"jsonrpc": "2.0",
95100
"id": 1,
96-
"method": "some_method",
101+
"method": "tools/call",
97102
"params": {
103+
"name": "get_weather",
104+
"arguments": {
105+
"city": "New York"
106+
},
98107
"_meta": {
99108
"modelcontextprotocol.io/task": {
100109
"taskId": "786512e2-9e0d-44bd-8f29-789f320fe840",
@@ -105,6 +114,28 @@ To create a task, requestors send a request with the `modelcontextprotocol.io/ta
105114
}
106115
```
107116

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+
108139
### Getting Tasks
109140

110141
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:
144175

145176
### Retrieving Task Results
146177

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+
147180
To retrieve the result of a completed task, requestors send a `tasks/result` request:
148181

149182
**Request:**
@@ -381,7 +414,8 @@ stateDiagram-v2
381414

382415
### Result Retrieval
383416

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`.
385419
1. Receivers **MUST** return an error if `tasks/result` is called for a task in any other status.
386420
1. Requestors **MAY** call `tasks/result` multiple times for the same task while it remains available.
387421

@@ -424,8 +458,8 @@ sequenceDiagram
424458
participant S as Server (Receiver)
425459
Note over C,S: 1. Task Creation
426460
C->>S: Request with task metadata (taskId, keepAlive)
461+
S->>C: CreateTaskResult (taskId, status: submitted, keepAlive, pollInterval)
427462
S--)C: notifications/tasks/created
428-
Note over C,S: Original request will respond eventually,<br/>but requestor uses task polling instead
429463
Note over C,S: 2. Task Polling
430464
C->>S: tasks/get (taskId)
431465
S->>C: submitted
@@ -458,8 +492,8 @@ sequenceDiagram
458492
459493
Note over C,S: Client augments with task metadata
460494
C->>S: tools/call (task-123, keepAlive: 3600000)
495+
S->>C: CreateTaskResult (task-123, status: submitted)
461496
S--)C: notifications/tasks/created
462-
Note over C,S: Original request will respond eventually,<br/>but client uses task polling instead
463497
464498
Note over LLM,C: Client continues processing other requests<br/>while task executes in background
465499
LLM->>C: Request other operation
@@ -515,8 +549,8 @@ sequenceDiagram
515549
516550
Note over S,C: Server requests client operation (task-augmented)
517551
S->>C: sampling/createMessage (request-789, keepAlive: 3600000)
552+
C->>S: CreateTaskResult (request-789, status: submitted)
518553
C--)S: notifications/tasks/created
519-
Note over S,C: Original request will respond eventually,<br/>but server uses task polling instead
520554
521555
Note over S: Server continues processing<br/>while waiting for result
522556
@@ -589,6 +623,7 @@ sequenceDiagram
589623
590624
Note over C,S: 1. Task Creation and Completion
591625
C->>S: tools/call (task-123)
626+
S->>C: CreateTaskResult (task-123, status: submitted)
592627
S--)C: notifications/tasks/created
593628
Note over S: Task processing...
594629
C->>S: tasks/get (task-123)

docs/specification/draft/schema.mdx

Lines changed: 9 additions & 1 deletion
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

0 commit comments

Comments
 (0)