Skip to content

Commit 20b8e86

Browse files
committed
fix: keep logging levels per session
1 parent 48c0cc9 commit 20b8e86

5 files changed

Lines changed: 155 additions & 33 deletions

File tree

‎docs/_server/index.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,7 @@ It implements the Model Context Protocol specification, handling model context r
3939
- Multi round-trip `input_required` results (MCP 2026-07-28, SEP-2322): handlers return `MCP::Server::InputRequiredResult` to ask
4040
the client for additional input instead of performing a server-initiated request; see [Multi Round-Trip Requests](/server/mrtr/)
4141
- `ping` - Simple health check
42-
- `logging/setLevel` - Configures the minimum log level for the server (deprecated as of 2026-07-28)
42+
- `logging/setLevel` - Configures the minimum log level for the calling session (deprecated as of 2026-07-28)
4343
- `tools/list` - Lists all registered tools and their schemas
4444
- `tools/call` - Invokes a specific tool with provided arguments
4545
- `prompts/list` - Lists all registered prompts and their schemas

‎docs/_server/logging.md‎

Lines changed: 37 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -35,8 +35,8 @@ The SDK supports 8 log levels with increasing severity:
3535

3636
## How Logging Works
3737

38-
1. **Client Configuration**: The client sends a `logging/setLevel` request to configure the minimum log level
39-
2. **Server Filtering**: The server only sends log messages at the configured level or higher severity
38+
1. **Client Configuration**: The client sends a `logging/setLevel` request to configure the minimum log level for its session only
39+
2. **Server Filtering**: The server only sends session-scoped log messages at the configured level or higher severity
4040
3. **Notification Delivery**: Log messages are sent as `notifications/message` to the client
4141

4242
For example, if the client sets the level to `"error"` (severity 4), the server will send messages with levels: `error`, `critical`, `alert`, and `emergency`.
@@ -45,44 +45,57 @@ For more details, see the [MCP Logging specification](https://modelcontextprotoc
4545

4646
**Usage Example:**
4747

48-
The client first configures the level with a `logging/setLevel` request:
48+
The client first configures the level for its session with a `logging/setLevel` request:
4949

5050
```json
5151
{ "jsonrpc": "2.0", "id": 1, "method": "logging/setLevel", "params": { "level": "info" } }
5252
```
5353

54-
The server then emits messages at each severity; only those at or above the configured level are delivered:
54+
The server then emits messages at each severity from a tool handler; only those at or above the calling session's configured level are delivered:
5555

5656
```ruby
5757
server = MCP::Server.new(name: "my_server")
5858
transport = MCP::Server::Transports::StdioTransport.new(server)
5959

60-
server.notify_log_message(
61-
data: { message: "Application started successfully" },
62-
level: "info"
63-
)
64-
65-
server.notify_log_message(
66-
data: { message: "Configuration file not found, using defaults" },
67-
level: "warning"
68-
)
69-
70-
server.notify_log_message(
71-
data: {
72-
error: "Database connection failed",
73-
details: { host: "localhost", port: 5432 }
74-
},
75-
level: "error",
76-
logger: "DatabaseLogger" # Optional logger name
77-
)
60+
server.define_tool(name: "log_messages") do |server_context:|
61+
server_context.notify_log_message(
62+
data: { message: "Application started successfully" },
63+
level: "info"
64+
)
65+
66+
server_context.notify_log_message(
67+
data: { message: "Configuration file not found, using defaults" },
68+
level: "warning"
69+
)
70+
71+
server_context.notify_log_message(
72+
data: {
73+
error: "Database connection failed",
74+
details: { host: "localhost", port: 5432 }
75+
},
76+
level: "error",
77+
logger: "DatabaseLogger" # Optional logger name
78+
)
79+
MCP::Tool::Response.new([{ type: "text", text: "ok" }])
80+
end
81+
transport.open
7882
```
7983

84+
`Server#notify_log_message` broadcasts use only the server-wide level, not a session's level. Applications can set the server-wide level explicitly:
85+
86+
```ruby
87+
server.logging_message_notification = MCP::LoggingMessageNotification.new(level: "info")
88+
```
89+
90+
`logging/setLevel` handled without a session still sets the server-wide level. Client requests through stdio and Streamable HTTP do not set it.
91+
8092
**Key Features:**
8193

8294
- Server has capability `logging` to send log messages
8395
- Messages are only sent if a transport is configured
84-
- Messages are filtered based on the client's configured log level
85-
- If the log level hasn't been set by the client, no messages will be sent
96+
- Session-scoped messages use the client's configured log level, or the server-wide default for legacy sessions without their own level
97+
- Server-wide broadcasts use only the server-wide log level
98+
- If no effective log level is configured, no messages will be sent
8699

87100
## Transport Support
88101

‎lib/mcp/server.rb‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1382,8 +1382,11 @@ def configure_logging_level(request, session: nil)
13821382
raise RequestHandlerError.new("Invalid log level #{request[:level]}", request, error_type: :invalid_params)
13831383
end
13841384

1385-
session&.configure_logging(logging_message_notification)
1386-
@logging_message_notification = logging_message_notification
1385+
if session
1386+
session.configure_logging(logging_message_notification)
1387+
else
1388+
@logging_message_notification = logging_message_notification
1389+
end
13871390

13881391
{}
13891392
end
Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
# frozen_string_literal: true
2+
3+
require "test_helper"
4+
require "open3"
5+
6+
module MCP
7+
class LoggingDocumentationTest < ActiveSupport::TestCase
8+
include InitializeParamsTestHelper
9+
10+
test "logging example honors the client's configured level" do
11+
documentation = File.read(File.expand_path("../../docs/_server/logging.md", __dir__))
12+
script = documentation[/```ruby\n(.*?)```/m, 1]
13+
refute_nil script
14+
15+
requests = [
16+
{ jsonrpc: "2.0", id: 1, method: "initialize", params: initialize_params(protocolVersion: "2025-11-25") },
17+
{ jsonrpc: "2.0", method: "notifications/initialized" },
18+
{ jsonrpc: "2.0", id: 2, method: "logging/setLevel", params: { level: "error" } },
19+
{ jsonrpc: "2.0", id: 3, method: "tools/call", params: { name: "log_messages", arguments: {} } },
20+
]
21+
input = requests.map { |request| JSON.generate(request) }.join("\n") + "\n"
22+
lib = File.expand_path("../../lib", __dir__)
23+
stdout, stderr, status = Open3.capture3(
24+
{ "RUBYOPT" => nil }, RbConfig.ruby, "-I", lib, "-r", "mcp", "-e", script, stdin_data: input,
25+
)
26+
assert_predicate status, :success?, stderr
27+
28+
messages = stdout.lines.map { |line| JSON.parse(line) }
29+
logs = messages.select { |message| message["method"] == "notifications/message" }
30+
assert_equal ["error"], logs.map { |message| message["params"]["level"] }
31+
assert_equal "DatabaseLogger", logs.first["params"]["logger"]
32+
assert_equal [1, 2, 3], messages.select { |message| message.key?("id") }.map { |message| message["id"] }
33+
response = messages.find { |message| message["id"] == 3 }
34+
assert_equal "ok", response["result"]["content"].first["text"]
35+
end
36+
end
37+
end

‎test/mcp/server_notification_test.rb‎

Lines changed: 75 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -302,22 +302,91 @@ def send_notification(method, params = nil)
302302
assert_equal Methods::NOTIFICATIONS_MESSAGE, notifications[3][:method]
303303
end
304304

305-
test "server.notify_log_message works after logging/setLevel via session" do
305+
test "logging/setLevel does not enable logs in other existing or future sessions" do
306+
session = ServerSession.new(server: @server, transport: @mock_transport)
307+
other_session = ServerSession.new(server: @server, transport: @mock_transport)
308+
@server.define_tool(name: "log_debug") do |server_context:|
309+
server_context.notify_log_message(data: "debug detail", level: "debug")
310+
Tool::Response.new([{ type: "text", text: "ok" }])
311+
end
312+
313+
response = session.handle(
314+
{ jsonrpc: "2.0", id: 1, method: "logging/setLevel", params: { level: "debug" } },
315+
)
316+
assert_equal({}, response[:result])
317+
future_session = ServerSession.new(server: @server, transport: @mock_transport)
318+
319+
[other_session, future_session].each do |unconfigured_session|
320+
response = unconfigured_session.handle(
321+
{ jsonrpc: "2.0", id: 2, method: "tools/call", params: { name: "log_debug", arguments: {} } },
322+
)
323+
assert_equal "ok", response[:result][:content].first[:text]
324+
end
325+
326+
assert_empty @mock_transport.notifications
327+
assert_nil @server.logging_message_notification
328+
329+
response = session.handle(
330+
{ jsonrpc: "2.0", id: 3, method: "tools/call", params: { name: "log_debug", arguments: {} } },
331+
)
332+
assert_equal "ok", response[:result][:content].first[:text]
333+
assert_equal 1, @mock_transport.notifications.size
334+
assert_equal "debug detail", @mock_transport.notifications.first[:params]["data"]
335+
end
336+
337+
test "logging/setLevel does not change an application-configured server-wide default" do
338+
default_logging = LoggingMessageNotification.new(level: "error")
339+
@server.logging_message_notification = default_logging
340+
session = ServerSession.new(server: @server, transport: @mock_transport)
341+
other_session = ServerSession.new(server: @server, transport: @mock_transport)
342+
343+
response = session.handle(
344+
{ jsonrpc: "2.0", id: 1, method: "logging/setLevel", params: { level: "debug" } },
345+
)
346+
assert_equal({}, response[:result])
347+
future_session = ServerSession.new(server: @server, transport: @mock_transport)
348+
349+
[other_session, future_session].each do |unconfigured_session|
350+
unconfigured_session.notify_log_message(data: "info detail", level: "info")
351+
unconfigured_session.notify_log_message(data: "error detail", level: "error")
352+
end
353+
@server.notify_log_message(data: "broadcast info", level: "info")
354+
@server.notify_log_message(data: "broadcast error", level: "error")
355+
session.notify_log_message(data: "session debug", level: "debug")
356+
357+
assert_equal ["error detail", "error detail", "broadcast error", "session debug"],
358+
@mock_transport.notifications.map { |notification| notification[:params]["data"] }
359+
assert_same default_logging, @server.logging_message_notification
360+
end
361+
362+
test "logging/setLevel via session does not enable server-wide broadcasts" do
306363
session = ServerSession.new(server: @server, transport: @mock_transport)
307364

308365
# Client sends logging/setLevel through session.
309-
@server.handle(
366+
response = @server.handle(
310367
{ jsonrpc: "2.0", id: 1, method: "logging/setLevel", params: { level: "info" } },
311368
session: session,
312369
)
370+
assert_equal({}, response[:result])
313371

314-
# Server-level broadcast should still work because logging level
315-
# is stored on both the session and the server.
316372
@server.notify_log_message(data: "broadcast log", level: "info")
317373

318374
log_notifications = @mock_transport.notifications.select { |n| n[:method] == Methods::NOTIFICATIONS_MESSAGE }
319-
assert_equal 1, log_notifications.size
320-
assert_equal "broadcast log", log_notifications.first[:params]["data"]
375+
assert_empty log_notifications
376+
end
377+
378+
test "logging/setLevel without a session configures server-wide broadcasts" do
379+
response = @server.handle(
380+
{ jsonrpc: "2.0", id: 1, method: "logging/setLevel", params: { level: "info" } },
381+
)
382+
assert_equal({}, response[:result])
383+
384+
@server.notify_log_message(data: "debug log", level: "debug")
385+
@server.notify_log_message(data: "broadcast log", level: "info")
386+
387+
assert_equal 1, @mock_transport.notifications.size
388+
assert_equal Methods::NOTIFICATIONS_MESSAGE, @mock_transport.notifications.first[:method]
389+
assert_equal "broadcast log", @mock_transport.notifications.first[:params]["data"]
321390
end
322391
end
323392
end

0 commit comments

Comments
 (0)