What it does
The `notifications/progress` notification is sent by whichever side initiated a long-running operation — typically the server, but also the client when it is processing a sampling request — to the counterpart that originally issued the request. It fires only when the initial request included a `progressToken` in its `_meta` field; without that token the sender must not emit progress notifications at all. The notification carries the same token so the receiver can correlate updates to the correct in-flight request, a monotonically increasing `progress` value, an optional `total`, and an optional human-readable `message`. The receiver's only obligation is to update its progress display or internal bookkeeping; it must not reply or acknowledge the notification. Because MCP notifications are fire-and-forget, the sender has no guarantee the receiver processed any individual update. Progress values must always increase — sending a value less than or equal to the previous value for the same token is a protocol violation and receivers may silently discard or log such out-of-order frames. Both sides must have negotiated support implicitly through normal capability exchange before the first request carrying a `progressToken` is sent. If the receiving side never sees a `progressToken` on a request, it should ignore any stray `notifications/progress` messages. When `total` is omitted the receiver should render an indeterminate progress indicator; when provided it should be treated as an estimate, not a hard bound, because implementations occasionally exceed it before the final response arrives.
When to use
Long-running operations the requester asked to track.
When NOT to use
Requests without a progressToken — silently no-op.
Notes
Capability gating via progressToken
Progress notifications are not gated by a separate capability flag in the spec. The contract is implicit: if you include a `progressToken` in a request's `_meta`, you are advertising that you accept progress notifications for that operation. Senders must never emit `notifications/progress` for a request that carried no token, and receivers that see such a notification without a matching in-flight token should discard it without error.
Monotonic ordering is required, not advisory
The spec mandates that `progress` values strictly increase for the lifetime of a given token. In practice, network reordering on stdio transports is impossible, but HTTP/SSE or custom transports may deliver frames out of order. Receivers should track the last-seen value per token and silently drop any notification whose `progress` does not exceed it, preventing a UI regression bar or misleading percentage.
Race conditions at completion
A progress notification may arrive after the final response for the same request, particularly under SSE where different HTTP responses can race. Receivers must be prepared to discard progress updates for tokens they have already resolved or rejected. Keeping a short-lived completion set — rather than removing the token immediately — prevents spurious errors when late-arriving frames are processed.
SDK handling differences
The official TypeScript SDK wraps progress emission behind a `progressToken` helper that auto-increments and validates monotonicity, making silent violations unlikely. The Python SDK exposes a lower-level `send_progress_notification` coroutine that performs no monotonicity check, so server authors are responsible for tracking the last emitted value. Neither SDK exposes a built-in timeout to abandon stale progress streams; long-running operations should implement their own cancellation via `notifications/cancelled` if the client disconnects.
Parameters
| Name | Type | Purpose |
|---|---|---|
| progressToken | string | number | Token from the original request. |
| progress | number | Increasing value. |
| total | number? | Upper bound, if known. |
| message | string? | Human description. |
Examples
Progress 50%
{ "method": "notifications/progress", "params": { "progressToken": "abc", "progress": 50, "total": 100 } }