Home Glossary
HomeGlossaryProgress Notification
MCP Glossary

Progress Notification

TL;DR

A progress notification is a server-to-client message that reports incremental progress for a long-running tool call. The client includes a `progressToken` when calling the tool, and the server sends `notifications/progress` messages referencing that token while the call is in flight.

In depth

Progress notifications solve the 'is this thing still working?' problem for long-running MCP tool calls. Without them, the client (and the user) sees a frozen UI until the tool returns. With them, the server streams updates — 'downloading', '42% complete', 'parsing' — keeping the UX responsive.

The mechanism: when the client calls a tool, it can include a `_meta.progressToken` in the request (any opaque value it chooses). The server sends `notifications/progress` messages with that token, a `progress` number, and optional `total` plus `message` text. The client routes these to the UI.

Progress is one-way (server→client) and advisory — not every operation needs to emit progress. Fast tools skip it. Long-running data imports, video processing, or multi-step scrapes benefit enormously.

The progress token convention also enables cancellation: the client can send `notifications/cancelled` with the same token, and a well-behaved server will abort the in-flight work.

Code example

// Client request with progress token
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "scrape_site",
    "arguments": { "url": "..." },
    "_meta": { "progressToken": "job-abc-123" }
  },
  "id": 1
}

// Server → Client progress notifications
{
  "jsonrpc": "2.0",
  "method": "notifications/progress",
  "params": {
    "progressToken": "job-abc-123",
    "progress": 42,
    "total": 100,
    "message": "Scraping page 42 of 100"
  }
}

// Final result comes as normal tool response

Examples

  • 1
    A scraping MCP emitting 'fetched 42/100 pages' progress events
  • 2
    A video-processing MCP reporting 'encoded 30%...' every second
  • 3
    A backup MCP showing 'uploaded 2.3GB of 8.1GB'
  • 4
    A long data import: 'inserted 10,000 rows / estimated 50,000'
  • 5
    An ML MCP: 'epoch 3/10 — loss 0.42'

What it's NOT

  • ✗Progress notifications are NOT required — many tools skip them.
  • ✗Progress is NOT the final result — the tool response still comes separately.
  • ✗Progress tokens are NOT secret — they're just correlation IDs the client picks.
  • ✗Progress does NOT guarantee completion — a tool can fail after emitting progress.

Related terms

Tool CallMCP TransportMCP ServerModel Context Protocol (MCP)

See also

  • MCP Utilities

Frequently asked questions

Should my tool emit progress?

If it runs longer than ~2 seconds, yes. Short tools should skip it to avoid noise.

Can progress notifications be canceled?

The client can send `notifications/cancelled` with the same token. Well-behaved servers abort in-flight work.

Is progress reliable over HTTP?

With streamable HTTP, yes — the server can interleave progress events with the final response.

Build with MCP

Browse 300+ MCP servers, explore recipes, or continue learning the MCP vocabulary.

Browse MarketplaceAll terms