Notifications

The server supports sending notifications to clients when lists of tools, prompts, or resources change. This enables real-time updates without polling.

Notification Methods

The server provides the following notification methods:

  • notify_tools_list_changed - Send a notification when the tools list changes
  • notify_prompts_list_changed - Send a notification when the prompts list changes
  • notify_resources_list_changed - Send a notification when the resources list changes
  • notify_log_message - Send a structured logging notification message (see Logging)

Session Scoping

When using Streamable HTTP transport with multiple clients, each client connection gets its own session. Notifications are scoped as follows:

  • report_progress and notify_log_message called via server_context inside a tool handler are automatically sent only to the requesting client. No extra configuration is needed.
  • notify_tools_list_changed, notify_prompts_list_changed, and notify_resources_list_changed are always broadcast to all connected clients, as they represent server-wide state changes. These should be called on the server instance directly.

On the modern lifecycle (MCP 2026-07-28), clients receive these broadcasts through the subscriptions/listen stream; see Notification Subscriptions.

Notification Format

Notifications follow the JSON-RPC 2.0 specification and use these method names:

  • notifications/tools/list_changed
  • notifications/prompts/list_changed
  • notifications/resources/list_changed
  • notifications/cancelled (see Cancellation)
  • notifications/progress (see Progress)
  • notifications/message (see Logging)

Broadcasting a List Change

Call the matching notify_* method after changing a server-wide list:

server = MCP::Server.new(name: "my_server")

# Default Streamable HTTP - session oriented
transport = MCP::Server::Transports::StreamableHTTPTransport.new(server)

# When tools change, notify clients
server.define_tool(name: "new_tool") { |**args| MCP::Tool::Response.new([{ type: "text", text: "ok" }]) }
server.notify_tools_list_changed

# When prompts change, notify clients
server.define_prompt(name: "new_prompt") do |args, server_context:|
  MCP::Prompt::Result.new(messages: [])
end
server.notify_prompts_list_changed

# When resources change, notify clients
server.define_resource(uri: "resource://new", name: "new_resource", mime_type: "text/plain") do
  [MCP::Resource::TextContents.new(uri: "resource://new", mime_type: "text/plain", text: "contents")]
end
server.notify_resources_list_changed