MCP progress notification

What is MCP progress notification?

‍

MCP progress notification is an MCP protocol message that lets a server stream progress updates back to the client during a long-running tool call. In the MCP spec, this is handled with the notifications/progress notification and an associated progressToken. (modelcontextprotocol.io)

Understanding MCP progress notification

‍

In practice, progress notifications give the client visibility into work that has started but has not finished yet. The caller includes a progressToken in the original request, and the receiver can send updates that report current progress, an optional total, and an optional human-readable message. The MCP spec also says these notifications are out-of-band and should stop when the operation completes. (modelcontextprotocol.io)

‍

This matters most for tool calls that may take seconds or minutes, like bulk processing, model-heavy computation, or long agent steps. For teams building MCP servers, progress notifications are a small protocol feature that improves UX without changing the core result format. For teams building clients, they make it easier to show spinners, percentages, and status text without guessing whether a request has stalled. Key aspects of MCP progress notification include:

1. Progress token: The request carries a token that ties updates back to the original call.
2. Incremental updates: The server can send repeated notifications as work advances.
3. Optional total: The client can receive a total when it is known, or just a running value.
4. Human-readable status: A message field can explain what the server is doing.
5. Terminal behavior: Updates should end once the operation is done. (modelcontextprotocol.io)

Advantages of MCP progress notification

‍

1. Better UX: Users see that a tool is still working instead of wondering if it froze.
2. Clearer long-running workflows: Clients can surface meaningful status during multi-step operations.
3. Protocol-level consistency: Progress reporting is standardized instead of custom per integration.
4. Works with unknown totals: The server can still report useful progress even when completion size is unclear.
5. Agent-friendly: It fits naturally into tool calls, task flows, and other asynchronous MCP interactions.

Challenges in MCP progress notification

‍

1. Token management: Implementations need to track which progress tokens are active.
2. Rate control: Sending too many notifications can flood the client.
3. Partial visibility: Progress values help, but they do not guarantee exact remaining time.
4. Client support: A notification is only useful if the client knows how to display it.
5. Lifecycle handling: Updates need to stop cleanly when the task finishes or fails. (modelcontextprotocol.io)

Example of MCP progress notification in action

‍

Scenario: a client asks an MCP server to process a large batch of documents. The request includes a progressToken, and the server starts work immediately.

As the job runs, the server sends notifications/progress messages like 10 percent, 40 percent, and 90 percent complete, plus short status text such as indexing, validating, or finalizing. The client can show those updates in real time while waiting for the final response.

This pattern is especially useful when the tool call is predictable enough to report movement, but not simple enough to finish instantly. It keeps the user informed without changing the underlying result payload. (modelcontextprotocol.io)

How PromptLayer helps with MCP progress notification

‍

PromptLayer helps teams observe and manage the prompt and tool workflows around MCP, including long-running agent steps where progress updates matter. By keeping prompt versions, runs, and evaluations organized, the PromptLayer team makes it easier to debug where a workflow slowed down and how its status messages behaved.

Ready to try it yourself? Sign up for PromptLayer and start managing your prompts in minutes.