Send Progress for Long Tasks
Stream percent-done updates to the client.
Send Progress for Long Tasks is a free MCP Academy lesson on CoddyKit — lesson 1 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the MCP Academy learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.
Why Progress Matters
When a tool takes seconds or minutes, the client should not just hang. MCP lets your server send progress updates so the user sees movement.
The Progress Token
The client opts in by attaching a progressToken to the request. Without that token, your server simply skips sending updates.
Reach the Context Object
In the Python SDK, a tool receives a Context object. It is your handle for talking back to the client mid-call, including progress.
from mcp.server.fastmcp import Context
@mcp.tool()
async def crunch(n: int, ctx: Context) -> str:
return "done"Call report_progress
To push an update, you call ctx.report_progress. Each call tells the client how far along the work has come.
await ctx.report_progress(progress=3, total=10)Progress and Total
The total argument is the finish line. The client can divide progress by total to draw a percent-done bar for the user.
await ctx.report_progress(progress=5, total=10) # 50%Update Inside a Loop
The natural place to report is inside your work loop. After each chunk finishes, send one update so the bar climbs steadily.
for i, item in enumerate(items):
process(item)
await ctx.report_progress(i + 1, len(items))Progress Without a Total
Sometimes you cannot know the total upfront. You may omit it; the client then shows an indeterminate spinner instead of a precise bar.
await ctx.report_progress(progress=42) # total unknownAdd an Optional Message
Many SDK versions let you attach a short message to a progress call, like "Indexing files", giving the user friendly human context.
await ctx.report_progress(2, 5, message="Fetching pages")It Is a Notification
Progress travels as a JSON-RPC notification, so it has no reply and never blocks. Your tool keeps working while updates flow out.
Keep Updates Reasonable
Do not flood the client with thousands of tiny updates. Report at meaningful steps so the stream stays useful and lightweight.
Progress Plus a Result
Progress notifications are separate from your tool's return value. You stream updates as you go, then hand back the final result at the end.
await ctx.report_progress(10, 10)
return "index built"Quick Check
Test your grasp of how progress reporting begins.
Recap: Progress
You learned to call ctx.report_progress with progress and total, loop your updates, and let the client draw a live bar. Nice work!
Frequently asked questions
Is the “Send Progress for Long Tasks” lesson free?
Yes — the full text of “Send Progress for Long Tasks” is free to read here on the web, and the MCP Academy course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the MCP Academy course, upgrade to CoddyKit PRO.
What will I learn in “Send Progress for Long Tasks”?
Stream percent-done updates to the client. You practise MCP Academy with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.
Do I need any experience to start MCP Academy?
No prior experience is required. MCP Academy on CoddyKit is structured for beginners through advanced learners; this is — lesson 1 of 4, so you can start here or from the beginning and move at your own pace.
How long does the “Send Progress for Long Tasks” lesson take?
Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.
Can I write and run code in this MCP Academy lesson?
Yes. Every MCP Academy lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.
All lessons in this course
- Send Progress for Long Tasks
- Handle Cancellation Requests
- Structured Logging to the Client
- Set Log Levels at Runtime