What it does
The `notifications/message` notification is the server's primary channel for emitting diagnostic log output to the client during an active MCP session. It fires any time the server-side application code calls its logging API — tool execution, resource reads, lifecycle hooks, or custom business logic can all trigger it. The server sends the notification over the JSON-RPC transport; the client receives it as a fire-and-forget message with no `id` field and must not reply. Firing can occur at any point after the `initialize` / `initialized` handshake completes; the server must never emit log notifications before the session is fully established. The notification carries three fields: `level` (a required `LoggingLevel` string following RFC 5424 severity ordering from `debug` through `emergency`), an optional `logger` string identifying the subsystem (e.g., `"db"` or `"auth"`), and `data` — any JSON-serialisable value. Before emitting, the server is responsible for comparing the message's `level` against the threshold most recently set by `logging/setLevel`; messages below that threshold must be suppressed. If the client has never called `logging/setLevel`, the server applies its own default threshold, usually `warning`. For the server to send this notification at all, it must declare the `logging` capability — an empty object `{}` — inside `ServerCapabilities` during `initialize`. If the server omits the `logging` capability, clients may treat any `notifications/message` it receives as a protocol violation and discard or log a warning. The MCP spec imposes no ordering guarantee between log notifications and other in-flight responses; clients must buffer or render log entries independently of pending request/response pairs.
When to use
For diagnostic output the user/host should see.
When NOT to use
For protocol errors — use JSONRPCError.
Notes
Capability declaration is mandatory
The server must include `"logging": {}` in its `ServerCapabilities` response during initialization. Omitting it means the server is not advertising log support; a spec-compliant client is permitted to ignore or reject any `notifications/message` frames it unexpectedly receives. Always declare the capability even if you only plan to emit logs occasionally.
Level filtering is server-side, not client-side
Although clients call `logging/setLevel` to declare their desired threshold, the spec places the suppression responsibility on the server. The server must stop emitting notifications below the negotiated level rather than relying on the client to discard them. This matters for bandwidth: on low-throughput transports (SSE, WebSocket with message size limits), flooding the client with debug frames and expecting it to drop them is a spec violation and a performance hazard.
Race condition around setLevel timing
There is an inherent race: a client may send `logging/setLevel` while the server is mid-request and has already queued several notifications at a verbose level. The server should apply the new threshold to all notifications dispatched after it processes the `setLevel` request, but notifications already written to the transport will have been sent. Clients should not assume strict level enforcement for the brief window between their `setLevel` call and the server's acknowledgement.
SDK differences in default threshold
The official Python SDK defaults to emitting `debug` and above until overridden, while the TypeScript SDK defaults to `info`. This means identical server code can produce different verbosity in practice depending on which SDK the server uses and which SDK the client uses to interpret the threshold. Always call `logging/setLevel` early in the session if your client has a specific verbosity requirement rather than relying on a shared default.
Parameters
| Name | Type | Purpose |
|---|---|---|
| level | LoggingLevel | Severity. |
| logger | string? | Logger name (e.g., 'db', 'auth'). |
| data | unknown | JSON-serialisable payload. |
Examples
Warning log
{ "method": "notifications/message", "params": { "level": "warning", "data": "Rate limit close" } }