What it does
The `notifications/prompts/list_changed` notification is sent by the server to the client whenever the set of available prompts changes at runtime. This fires during state transitions such as loading or unloading prompt definitions, when the server dynamically registers new prompt templates based on configuration, when a prompt becomes unavailable due to a missing resource or permission change, or when any prompt's metadata (name, arguments, description) is updated in a way that alters what the client would discover via `prompts/list`. The server is the sole sender of this notification; the client receives it passively over the active session transport. Upon receipt, the client MUST treat its cached prompt list as stale and issue a fresh `prompts/list` request before relying on any prompt metadata. Clients that skip re-fetching risk operating on an outdated prompt inventory, which can lead to failed `prompts/get` calls or silently wrong prompt arguments. Capability gating is strict: the server MUST declare `prompts.listChanged: true` in its `capabilities` block during the `initialize` handshake, and the client MUST have acknowledged the `prompts` capability. If either side omits the capability, the notification must not be sent and, if received unexpectedly, should be silently ignored rather than treated as a protocol error.
When to use
When prompts are added/removed.
When NOT to use
For prompt content tweaks — clients re-fetch on use.
Notes
Capability must be declared at init
The server must include `prompts: { listChanged: true }` in its capabilities object during the `initialize` response. Sending this notification without declaring the capability is a protocol violation. Clients that did not negotiate the capability are permitted to silently drop the notification rather than surface an error, so omitting the declaration will cause clients to miss updates silently.
Re-fetch is required, not optional
The notification carries no payload describing what changed — it is purely a cache-invalidation signal. The client cannot infer which prompts were added, removed, or modified. A conforming client must issue a new `prompts/list` call immediately upon receipt and replace its entire cached list. Partial invalidation logic based on guessing which entry changed is not safe.
Race conditions between notification and list response
Because the notification and subsequent `prompts/list` response travel over the same ordered channel, the list response reflects the state at or after the change that triggered the notification — never a stale snapshot from before it. However, a second change can arrive between a client issuing `prompts/list` and receiving its response, so clients should be prepared to receive another `notifications/prompts/list_changed` before their in-flight list request resolves and re-fetch again.
SDK handling varies by implementation
The TypeScript MCP SDK exposes a `setRequestHandler` pattern where the server calls `server.sendPromptListChanged()` to emit this notification automatically when the registered prompt set changes. Python SDK users typically call `server.request_context` or trigger it manually. In both cases the transport layer guarantees delivery ordering, but high-frequency prompt churn should be debounced server-side to avoid flooding the client with redundant re-fetches.
Examples
Prompts changed
{ "method": "notifications/prompts/list_changed" }