Wiki · Concept · Last reviewed June 25, 2026

MCP Progress

MCP progress is the Model Context Protocol utility for optional progress tracking on long-running operations through request metadata and progress notifications.

Category: Concept Published: June 25, 2026 Modified: June 25, 2026 Last reviewed: June 25, 2026 Tags: MCP, Progress, AI Agents, Long-Running Tasks, Observability

Definition

MCP progress is a base utility in the Model Context Protocol. The 2025-11-25 specification says MCP supports optional progress tracking for long-running operations through notification messages. Either side can send progress notifications to provide operation-status updates.

Progress is not the same as completion, cancellation, or an audit trail. It is a live status channel tied to a request. A progress message can help a user understand that work is still moving, but it does not by itself prove that the result is correct, authorized, reversible, or safely completed.

How It Works

When a party wants progress updates for a request, it includes a progressToken inside request metadata. The progress page says progress tokens must be strings or integers and must be unique across all active requests. The receiver may then send notifications/progress messages that contain the same token, the current progress value, and optional total and message fields.

The current progress value must increase with each notification, even when total work is unknown. The progress and total values may be floating point numbers. The optional message field should provide relevant human-readable progress information. Receivers may choose not to send progress notifications, may decide their own frequency, and may omit total when unknown.

Implementations should track active progress tokens and rate limit progress messages to prevent flooding. Progress notifications must stop after completion. This makes progress a bounded signal, not an open-ended status feed.

Task Lifetime

Progress has special rules for MCP Tasks. For task-augmented requests, the original progressToken remains valid throughout the task's lifetime, even after the task creation result has been returned. Progress notifications for tasks must use the same token that appeared in the initial task-augmented request.

The specification also says task progress notifications must stop after the task reaches a terminal status: completed, failed, or cancelled. That matters because tasks are durable state machines, while ordinary progress is just a notification stream for an in-progress operation.

Governance Requirements

A governed deployment should log the request ID, method, sender, receiver, progress token or token hash, task ID if present, progress value, total value if present, message text, timestamp, and whether the update was displayed to a user. If messages may contain operational details, the logging policy should classify and redact them the same way it handles diagnostic logs.

User interfaces should label progress carefully. "50 of 100" may mean completed records, downloaded bytes, elapsed steps, internal phases, or a server-defined estimate. The client should not imply more precision than the server actually provides. If the total is omitted, the interface should not invent one.

Failure Modes

False precision. A client turns loosely defined progress values into a confident progress bar that users interpret as an objective measure.

Token reuse. A sender reuses a progress token across active requests, mixing updates from different operations.

Message leakage. Human-readable progress messages include file names, customer identifiers, prompts, paths, query fragments, or other sensitive details.

Zombie progress. Notifications continue after completion or after a task reaches a terminal status, making the UI appear alive after the underlying operation is done.

Source Discipline

Claims about MCP progress should cite the versioned progress specification. Claims about task lifetime should cite the progress page and the tasks specification. Security claims about progress messages should be framed as governance recommendations unless tied directly to broader MCP security guidance.

Spiralist Reading

Progress is the ritual of visible motion. It reassures the user that the agent has not vanished, that the task has a pulse, that waiting is not wasted.

The Spiralist caution is that motion is not meaning. A progress bar can soothe anxiety while hiding uncertainty, failure, or a bad plan. Good progress reporting tells the user what is moving, what remains unknown, and when intervention is still possible.

Open Questions

Sources

Return to Wiki