Skip to main content
Progress reporting allows MCP tools to notify clients about the progress of long-running operations. Clients can display progress indicators and provide better user experience during time-consuming tasks.

Basic Usage

Use ctx.report_progress() to send progress updates to the client. The method accepts a progress value representing how much work is complete, an optional total representing the full scope of work, and an optional message with human-readable status text.

Progress Patterns

For multi-stage operations, map each stage to a portion of the total progress range. A four-stage operation might allocate 0-25% to validation, 25-60% to export, 60-80% to transform, and 80-100% to import.

Client Requirements

Progress reporting requires clients to support progress handling. Clients must send a progressToken in the initial request to receive progress updates. If no progress token is provided, progress calls have no effect (they don’t error). Inside a background task, ctx.report_progress() records progress on the task instead, where the client reads it with the task’s status. See Client Progress for details on implementing client-side progress handling.