What it does
The notifications/cancelled notification is a fire-and-forget JSON-RPC 2.0 message sent by either side of an MCP connection — client or server — to signal that a previously issued request should be abandoned. It fires as soon as the sender decides to abort: typically when a user explicitly cancels an operation, a timeout elapses on the sender's side, or a higher-level workflow tears down mid-flight. The notification carries the requestId of the outstanding request so the receiver can correlate it with its own in-flight work queue. No capability negotiation is required to send or receive this notification; it is always available in the protocol.
Upon receiving notifications/cancelled, the receiver MAY stop processing the identified request and SHOULD emit a JSON-RPC error response (error code -32800, "Request cancelled") if it chooses to acknowledge the abort. Critically, however, cancellation is purely best-effort: the receiver is under no obligation to halt, and the sender must not assume work has stopped. If the response for the cancelled requestId arrives before the notification is processed, the sender must still handle it correctly.
Because the notification travels over the same ordered channel as responses, a race condition is inherent: the response may already be in flight when the cancel is sent. Implementations must therefore be prepared for two outcomes — receiving a normal result despite having sent the cancel, or receiving an error acknowledging the cancel. Neither outcome is erroneous, and callers must handle both without error.
When to use
User aborts a request before completion.
When NOT to use
For long-running tasks — use tasks/cancel.
Notes
No capability gating required
Unlike list-changed notifications that require a matching sub-capability declared during initialization, notifications/cancelled requires no prior capability negotiation. Either side may send it at any time after the connection is established, as long as there is an active in-flight request with the referenced requestId.
Race conditions are unavoidable
Because MCP uses ordered channels, the cancel notification and the response can cross in transit. The sender must always be prepared to receive a valid result for a requestId it already cancelled. Discarding such a response silently is correct behavior; treating it as an error is not. Applications that cannot tolerate stale results should maintain a local set of cancelled IDs and drop responses for them.
Error response is optional, not mandatory
The spec says the receiver SHOULD respond with an error (code -32800) if it stops processing, but MAY ignore the notification entirely and complete normally. SDKs differ here: the Python MCP SDK raises a McpError on the caller's Future when it detects the cancel, while the TypeScript SDK resolves the pending promise with an error only if the server explicitly responds. Do not rely on a consistent error signal across implementations.
Not a substitute for tasks/cancel on long-running work
For operations modelled as MCP Tasks (with a taskId and a status lifecycle), use the tasks/cancel method instead. notifications/cancelled is intended for short request/response pairs where no task object exists. Sending it against a taskId-bearing operation is undefined behavior and most servers will ignore it or return an error unrelated to the task lifecycle.
Parameters
| Name | Type | Purpose |
|---|---|---|
| requestId | string | number? | Request to cancel. |
| reason | string? | Free-form reason. |
Examples
Cancel request 7
{ "method": "notifications/cancelled", "params": { "requestId": 7, "reason": "user aborted" } }