mcp/08_progress.md

Progress

Source: https://modelcontextprotocol.io/specification/2025-11-25/basic/utilities/progress

Protocol Revision: 2025-11-25

The Model Context Protocol (MCP) supports optional progress tracking for long-running operations through notification messages. Either side can send progress notifications to provide updates about operation status.

Progress Flow

When a party wants to receive progress updates for a request, it includes a progressToken in the request metadata.

• Progress tokens MUST be a string or integer value
• Progress tokens can be chosen by the sender using any means, but MUST be unique across all active requests.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "some_method",
  "params": {
    "_meta": {
      "progressToken": "abc123"
    }
  }
}

The receiver MAY then send progress notifications containing:

• The original progress token
• The current progress value so far
• An optional "total" value
• An optional "message" value

{
  "jsonrpc": "2.0",
  "method": "notifications/progress",
  "params": {
    "progressToken": "abc123",
    "progress": 50,
    "total": 100,
    "message": "Reticulating splines..."
  }
}

• The progress value MUST increase with each notification, even if the total is unknown.
• The progress and the total values MAY be floating point.
• The message field SHOULD provide relevant human readable progress information.

Behavior Requirements

1. Progress notifications MUST only reference tokens that:

   • Were provided in an active request
   • Are associated with an in-progress operation

2. Receivers of progress requests MAY:

   • Choose not to send any progress notifications
   • Send notifications at whatever frequency they deem appropriate
   • Omit the total value if unknown

3. For task-augmented requests, the progressToken provided in the original request MUST continue to be used for progress notifications throughout the task's lifetime, even after the CreateTaskResult has been returned. The progress token remains valid and associated with the task until the task reaches a terminal status.

   • Progress notifications for tasks MUST use the same progressToken that was provided in the initial task-augmented request
   • Progress notifications for tasks MUST stop after the task reaches a terminal status (completed, failed, or cancelled)

sequenceDiagram
    participant Sender
    participant Receiver

    Note over Sender,Receiver: Request with progress token
    Sender->>Receiver: Method request with progressToken

    Note over Sender,Receiver: Progress updates
    Receiver-->>Sender: Progress notification (0.2/1.0)
    Receiver-->>Sender: Progress notification (0.6/1.0)
    Receiver-->>Sender: Progress notification (1.0/1.0)

    Note over Sender,Receiver: Operation complete
    Receiver->>Sender: Method response

Implementation Notes

• Senders and receivers SHOULD track active progress tokens
• Both parties SHOULD implement rate limiting to prevent flooding
• Progress notifications MUST stop after completion