Skip to content

Commit 4e9a387

Browse files
jbajba
authored
doc: document logging (#497)
For #442.
1 parent 84a568b commit 4e9a387

File tree

4 files changed

+175
-2
lines changed

4 files changed

+175
-2
lines changed

‎docs/server.md‎

Lines changed: 84 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -450,7 +450,90 @@ _ = mcp.NewServer(&mcp.Implementation{Name: "server"}, &mcp.ServerOptions{
450450

451451
### Logging
452452

453-
<!-- TODO -->
453+
MCP servers can send logging messages to MCP clients.
454+
(This form of logging is distinct from server-side logging, where the
455+
server produces logs that remain server-side, for use by server maintainers.)
456+
457+
**Server-side**:
458+
The minimum log level is part of the server state.
459+
For stateful sessions, there is no default log level: no log messages will be sent
460+
until the client calls `SetLevel` (see below).
461+
For stateful sessions, the level defaults to "info".
462+
463+
[`ServerSession.Log`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#ServerSession.Log) is the low-level way for servers to log to clients.
464+
It sends a logging notification to the client if the level of the message
465+
is at least the minimum log level.
466+
467+
For a simpler API, use [`NewLoggingHandler`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#NewLoggingHandler) to obtain a [`slog.Handler`](https://pkg.go.dev/log/slog#Handler).
468+
By setting [`LoggingHandlerOptions.MinInterval`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#LoggingHandlerOptions.MinInterval), the handler can be rate-limited
469+
to avoid spamming clients with too many messages.
470+
471+
Servers always report the logging capability.
472+
473+
474+
**Client-side**:
475+
Set [`ClientOptions.LoggingMessageHandler`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#ClientOptions.LoggingMessageHandler) to receive log messages.
476+
477+
Call [`ClientSession.SetLevel`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#ClientSession.SetLevel) to change the log level for a session.
478+
479+
```go
480+
func Example_logging() {
481+
ctx := context.Background()
482+
483+
// Create a server.
484+
s := mcp.NewServer(&mcp.Implementation{Name: "server", Version: "v0.0.1"}, nil)
485+
486+
// Create a client that displays log messages.
487+
done := make(chan struct{}) // solely for the example
488+
var nmsgs atomic.Int32
489+
c := mcp.NewClient(
490+
&mcp.Implementation{Name: "client", Version: "v0.0.1"},
491+
&mcp.ClientOptions{
492+
LoggingMessageHandler: func(_ context.Context, r *mcp.LoggingMessageRequest) {
493+
m := r.Params.Data.(map[string]any)
494+
fmt.Println(m["msg"], m["value"])
495+
if nmsgs.Add(1) == 2 { // number depends on logger calls below
496+
close(done)
497+
}
498+
},
499+
})
500+
501+
// Connect the server and client.
502+
t1, t2 := mcp.NewInMemoryTransports()
503+
ss, err := s.Connect(ctx, t1, nil)
504+
if err != nil {
505+
log.Fatal(err)
506+
}
507+
defer ss.Close()
508+
cs, err := c.Connect(ctx, t2, nil)
509+
if err != nil {
510+
log.Fatal(err)
511+
}
512+
defer cs.Close()
513+
514+
// Set the minimum log level to "info".
515+
if err := cs.SetLoggingLevel(ctx, &mcp.SetLoggingLevelParams{Level: "info"}); err != nil {
516+
log.Fatal(err)
517+
}
518+
519+
// Get a slog.Logger for the server session.
520+
logger := slog.New(mcp.NewLoggingHandler(ss, nil))
521+
522+
// Log some things.
523+
logger.Info("info shows up", "value", 1)
524+
logger.Debug("debug doesn't show up", "value", 2)
525+
logger.Warn("warn shows up", "value", 3)
526+
527+
// Wait for them to arrive on the client.
528+
// In a real application, the log messages would appear asynchronously
529+
// while other work was happening.
530+
<-done
531+
532+
// Output:
533+
// info shows up 1
534+
// warn shows up 3
535+
}
536+
```
454537

455538
### Pagination
456539

‎internal/docs/server.src.md‎

Lines changed: 27 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -215,7 +215,33 @@ requests.
215215

216216
### Logging
217217

218-
<!-- TODO -->
218+
MCP servers can send logging messages to MCP clients.
219+
(This form of logging is distinct from server-side logging, where the
220+
server produces logs that remain server-side, for use by server maintainers.)
221+
222+
**Server-side**:
223+
The minimum log level is part of the server state.
224+
For stateful sessions, there is no default log level: no log messages will be sent
225+
until the client calls `SetLevel` (see below).
226+
For stateful sessions, the level defaults to "info".
227+
228+
[`ServerSession.Log`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#ServerSession.Log) is the low-level way for servers to log to clients.
229+
It sends a logging notification to the client if the level of the message
230+
is at least the minimum log level.
231+
232+
For a simpler API, use [`NewLoggingHandler`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#NewLoggingHandler) to obtain a [`slog.Handler`](https://pkg.go.dev/log/slog#Handler).
233+
By setting [`LoggingHandlerOptions.MinInterval`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#LoggingHandlerOptions.MinInterval), the handler can be rate-limited
234+
to avoid spamming clients with too many messages.
235+
236+
Servers always report the logging capability.
237+
238+
239+
**Client-side**:
240+
Set [`ClientOptions.LoggingMessageHandler`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#ClientOptions.LoggingMessageHandler) to receive log messages.
241+
242+
Call [`ClientSession.SetLevel`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#ClientSession.SetLevel) to change the log level for a session.
243+
244+
%include ../../mcp/server_example_test.go logging -
219245

220246
### Pagination
221247

‎mcp/logging.go‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -70,6 +70,7 @@ type LoggingHandlerOptions struct {
7070
// The value for the "logger" field of logging notifications.
7171
LoggerName string
7272
// Limits the rate at which log messages are sent.
73+
// Excess messages are dropped.
7374
// If zero, there is no rate limiting.
7475
MinInterval time.Duration
7576
}

‎mcp/server_example_test.go‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,8 @@ import (
88
"context"
99
"fmt"
1010
"log"
11+
"log/slog"
12+
"sync/atomic"
1113

1214
"github.com/modelcontextprotocol/go-sdk/mcp"
1315
)
@@ -83,6 +85,67 @@ func Example_prompts() {
8385

8486
// !-prompts
8587

88+
// !+logging
89+
90+
func Example_logging() {
91+
ctx := context.Background()
92+
93+
// Create a server.
94+
s := mcp.NewServer(&mcp.Implementation{Name: "server", Version: "v0.0.1"}, nil)
95+
96+
// Create a client that displays log messages.
97+
done := make(chan struct{}) // solely for the example
98+
var nmsgs atomic.Int32
99+
c := mcp.NewClient(
100+
&mcp.Implementation{Name: "client", Version: "v0.0.1"},
101+
&mcp.ClientOptions{
102+
LoggingMessageHandler: func(_ context.Context, r *mcp.LoggingMessageRequest) {
103+
m := r.Params.Data.(map[string]any)
104+
fmt.Println(m["msg"], m["value"])
105+
if nmsgs.Add(1) == 2 { // number depends on logger calls below
106+
close(done)
107+
}
108+
},
109+
})
110+
111+
// Connect the server and client.
112+
t1, t2 := mcp.NewInMemoryTransports()
113+
ss, err := s.Connect(ctx, t1, nil)
114+
if err != nil {
115+
log.Fatal(err)
116+
}
117+
defer ss.Close()
118+
cs, err := c.Connect(ctx, t2, nil)
119+
if err != nil {
120+
log.Fatal(err)
121+
}
122+
defer cs.Close()
123+
124+
// Set the minimum log level to "info".
125+
if err := cs.SetLoggingLevel(ctx, &mcp.SetLoggingLevelParams{Level: "info"}); err != nil {
126+
log.Fatal(err)
127+
}
128+
129+
// Get a slog.Logger for the server session.
130+
logger := slog.New(mcp.NewLoggingHandler(ss, nil))
131+
132+
// Log some things.
133+
logger.Info("info shows up", "value", 1)
134+
logger.Debug("debug doesn't show up", "value", 2)
135+
logger.Warn("warn shows up", "value", 3)
136+
137+
// Wait for them to arrive on the client.
138+
// In a real application, the log messages would appear asynchronously
139+
// while other work was happening.
140+
<-done
141+
142+
// Output:
143+
// info shows up 1
144+
// warn shows up 3
145+
}
146+
147+
// !-logging
148+
86149
// !+resources
87150
func Example_resources() {
88151
ctx := context.Background()

0 commit comments

Comments
 (0)