Structured Logging to the Client

Printing to your terminal only helps you. MCP lets the server send log messages over the protocol so the host app can show them too.

Logs travel as a notifications/message notification. It carries a level, optional logger name, and the data you want recorded.

From inside a tool you reach logging through the Context object, the same handle you used for progress. No extra setup is needed.

The most common helper is ctx.info. Use it for normal, expected status notes that help a user follow what the tool is doing.

Reach for ctx.debug when you want fine-grained traces, like a parsed value or a chosen branch, that are noisy in everyday use.

Use ctx.warning when something is off but recoverable, like a missing optional field that you filled with a default value.

Call ctx.error for genuine problems. It tells the client a step failed, separate from raising an exception that ends the call.

MCP follows the familiar syslog scale: debug, info, notice, warning, error, critical, and higher. Clients can sort and color by level.

Many helpers accept a logger name so messages can be grouped by component, much like Python's standard logging module does.

Log messages leave your process and reach the client, so treat them as visible. Never write secrets like tokens or passwords into a log.

Like progress, each log is a notification, so it never blocks your tool or expects a reply. You can log freely as the work unfolds.

Pick the right helper for routine status updates.

You can now emit leveled logs with ctx.info, debug, warning, and error, name your loggers, and keep secrets out. Great progress!