MCP Advanced: Logging, Progress Notifications, Context Methods for Long Tasks

Logging and progress notifications are mechanisms that let MCP servers send real-time feedback to clients during long-running tool operations. Without them, users see nothing while a tool runs and cannot tell if the operation is working or has stalled. With notifications enabled, users get progress bars, status messages, and detailed logs showing exactly what is happening behind the scenes. These features are implemented through the Context object that the Python MCP SDK automatically provides to tool functions when they declare a context parameter.

You send log messages by calling the info method on the Context object inside your tool function. The context is automatically injected when you include it as a parameter in your tool definition. For example, calling await context.info with a string like "About to do research" sends that message to the client in real time. The info method is one of several logging levels available. These messages help users understand what phase of processing the tool is currently in, especially for operations that take several seconds or more.

You report progress by calling the report_progress method on the Context object with two arguments: the current progress value and the total value. For example, await context.report_progress with arguments 20 and 100 means 20 percent complete. You call this method at key checkpoints in your tool function, such as after fetching data and before generating a report. The client receives these values and can display them as a progress bar, percentage, or any other visual indicator. Both values are numbers, and the total can be None if the total is unknown.

The client handles these by defining two separate callback functions. The logging callback receives a LoggingMessageNotificationParams object and can print or display the log data however the application needs. The progress callback receives progress, total, and message parameters and can calculate percentages or update UI elements. You pass the logging callback when creating the ClientSession, and the progress callback when making individual tool calls via the call_tool method. This separation lets you handle different notification types independently.

Presentation depends entirely on your application type. Command-line applications can simply print messages and progress to the terminal. Web applications can push updates to the browser using WebSockets, server-sent events, or polling. Desktop applications can update progress bars and status displays in their native UI. The MCP server does not prescribe how notifications should be displayed. It only emits the data, and the client application decides the presentation. You can also choose to ignore notifications completely if they are not needed for your use case.

No, implementing these notifications is entirely optional on both the server and client sides. A server can run tools without ever sending a log message or progress update, and a client can choose to ignore any notifications it receives. They are purely user experience enhancements designed to help users understand what is happening during long-running operations. However, for tools that take more than a few seconds, adding notifications dramatically improves perceived reliability because users can see that work is actually happening.

Logging callbacks handle informational messages about what the tool is doing, like status updates such as "fetching data" or "writing report." Progress callbacks handle numerical progress indicators showing how far along the operation is out of a total. Logging callbacks are set once at the session level when creating the ClientSession, while progress callbacks are set per individual tool call. This design lets you use the same logging strategy across all tools but customize progress display for specific operations that benefit from a progress bar. ---