Skip to content

Commit 7cb3a64

Browse files
mikekistlermikekistler
authored
Add articles on logging and progress (#717)
* Add articles on logging and progress * Address comments in PR review
1 parent 52b1ed5 commit 7cb3a64

22 files changed

+629
-5
lines changed

‎docs/concepts/elicitation/elicitation.md

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,15 @@
11
---
22
title: Elicitation
33
author: mikekistler
4-
description: Learn about the telemetry collected by the HttpRepl.
4+
description: Enable interactive AI experiences by requesting user input during tool execution.
55
uid: elicitation
66
---
77

8+
## Elicitation
9+
810
The **elicitation** feature allows servers to request additional information from users during interactions. This enables more dynamic and interactive AI experiences, making it easier to gather necessary context before executing tasks.
911

10-
## Server Support for Elicitation
12+
### Server Support for Elicitation
1113

1214
Servers request structured data from users with the [ElicitAsync] extension method on [IMcpServer].
1315
The C# SDK registers an instance of [IMcpServer] with the dependency injection container,
@@ -27,7 +29,7 @@ The following example demonstrates how a server could request a boolean response
2729

2830
[!code-csharp[](samples/server/Tools/InteractiveTools.cs?name=snippet_GuessTheNumber)]
2931

30-
## Client Support for Elicitation
32+
### Client Support for Elicitation
3133

3234
Elicitation is an optional feature so clients declare their support for it in their capabilities as part of the `initialize` request. In the MCP C# SDK, this is done by configuring an [ElicitationHandler] in the [McpClientOptions]:
3335

‎docs/concepts/logging/logging.md

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
---
2+
title: Logging
3+
author: mikekistler
4+
description: How to use the logging feature in the MCP C# SDK.
5+
uid: logging
6+
---
7+
8+
## Logging
9+
10+
MCP servers may expose log messages to clients through the [Logging utility].
11+
12+
[Logging utility]: https://modelcontextprotocol.io/specification/2025-06-18/server/utilities/logging
13+
14+
This document describes how to implement logging in MCP servers and how clients can consume log messages.
15+
16+
### Logging Levels
17+
18+
MCP uses the logging levels defined in [RFC 5424](https://tools.ietf.org/html/rfc5424).
19+
20+
The MCP C# SDK uses the standard .NET [ILogger] and [ILoggerProvider] abstractions, which support a slightly
21+
different set of logging levels. Here's the levels and how they map to standard .NET logging levels.
22+
23+
| Level | .NET | Description | Example Use Case |
24+
|-----------|------|-----------------------------------|------------------------------|
25+
| debug | ✓ | Detailed debugging information | Function entry/exit points |
26+
| info | ✓ | General informational messages | Operation progress updates |
27+
| notice | | Normal but significant events | Configuration changes |
28+
| warning | ✓ | Warning conditions | Deprecated feature usage |
29+
| error | ✓ | Error conditions | Operation failures |
30+
| critical | ✓ | Critical conditions | System component failures |
31+
| alert | | Action must be taken immediately | Data corruption detected |
32+
| emergency | | System is unusable | |
33+
34+
**Note:** .NET's [ILogger] also supports a `Trace` level (more verbose than Debug) log level.
35+
As there is no equivalent level in the MCP logging levels, Trace level logs messages are silently
36+
dropped when sending messages to the client.
37+
38+
[ILogger]: https://learn.microsoft.com/dotnet/api/microsoft.extensions.logging.ilogger
39+
[ILoggerProvider]: https://learn.microsoft.com/dotnet/api/microsoft.extensions.logging.iloggerprovider
40+
41+
### Server configuration and logging
42+
43+
MCP servers that implement the Logging utility must declare this in the capabilities sent in the
44+
[Initialization] phase at the beginning of the MCP session.
45+
46+
[Initialization]: https://modelcontextprotocol.io/specification/2025-06-18/basic/lifecycle#initialization
47+
48+
Servers built with the C# SDK always declare the logging capability. Doing so does not obligate the server
49+
to send log messages -- only allows it. Note that stateless MCP servers may not be capable of sending log
50+
messages as there may not be an open connection to the client on which the log messages could be sent.
51+
52+
The C# SDK provides an extension method [WithSetLoggingLevelHandler] on [IMcpServerBuilder] to allow the
53+
server to perform any special logic it wants to perform when a client sets the logging level. However, the
54+
SDK already takes care of setting the [LoggingLevel] in the [IMcpServer], so most servers will not need to
55+
implement this.
56+
57+
[IMcpServer]: https://modelcontextprotocol.github.io/csharp-sdk/api/ModelContextProtocol.Server.IMcpServer.html
58+
[IMcpServerBuilder]: https://modelcontextprotocol.github.io/csharp-sdk/api/Microsoft.Extensions.DependencyInjection.IMcpServerBuilder.html
59+
[WithSetLoggingLevelHandler]: https://modelcontextprotocol.github.io/csharp-sdk/api/Microsoft.Extensions.DependencyInjection.McpServerBuilderExtensions.html#Microsoft_Extensions_DependencyInjection_McpServerBuilderExtensions_WithSetLoggingLevelHandler_Microsoft_Extensions_DependencyInjection_IMcpServerBuilder_System_Func_ModelContextProtocol_Server_RequestContext_ModelContextProtocol_Protocol_SetLevelRequestParams__System_Threading_CancellationToken_System_Threading_Tasks_ValueTask_ModelContextProtocol_Protocol_EmptyResult___
60+
[LoggingLevel]: https://modelcontextprotocol.github.io/csharp-sdk/api/ModelContextProtocol.Server.IMcpServer.html#ModelContextProtocol_Server_IMcpServer_LoggingLevel
61+
62+
MCP Servers using the MCP C# SDK can obtain an [ILoggerProvider] from the IMcpServer [AsClientLoggerProvider] extension method,
63+
and from that can create an [ILogger] instance for logging messages that should be sent to the MCP client.
64+
65+
[!code-csharp[](samples/server/Tools/LoggingTools.cs?name=snippet_LoggingConfiguration)]
66+
67+
[ILoggerProvider]: https://learn.microsoft.com/dotnet/api/microsoft.extensions.logging.iloggerprovider
68+
[AsClientLoggerProvider]: https://modelcontextprotocol.github.io/csharp-sdk/api/ModelContextProtocol.Server.McpServerExtensions.html#ModelContextProtocol_Server_McpServerExtensions_AsClientLoggerProvider_ModelContextProtocol_Server_IMcpServer_
69+
[ILogger]: https://learn.microsoft.com/dotnet/api/microsoft.extensions.logging.ilogger
70+
71+
### Client support for logging
72+
73+
When the server indicates that it supports logging, clients should configure
74+
the logging level to specify which messages the server should send to the client.
75+
76+
Clients should check if the server supports logging by checking the [Logging] property of the [ServerCapabilities] field of [IMcpClient].
77+
78+
[IMcpClient]: https://modelcontextprotocol.github.io/csharp-sdk/api/ModelContextProtocol.Client.IMcpClient.html
79+
[ServerCapabilities]: https://modelcontextprotocol.github.io/csharp-sdk/api/ModelContextProtocol.Client.IMcpClient.html#ModelContextProtocol_Client_IMcpClient_ServerCapabilities
80+
[Logging]: https://modelcontextprotocol.github.io/csharp-sdk/api/ModelContextProtocol.Protocol.ServerCapabilities.html#ModelContextProtocol_Protocol_ServerCapabilities_Logging
81+
82+
[!code-csharp[](samples/client/Program.cs?name=snippet_LoggingCapabilities)]
83+
84+
If the server supports logging, the client should set the level of log messages it wishes to receive with
85+
the [SetLoggingLevel] method on [IMcpClient]. If the client does not set a logging level, the server might choose
86+
to send all log messages or none -- this is not specified in the protocol -- so it is important that the client
87+
sets a logging level to ensure it receives the desired log messages and only those messages.
88+
89+
The `loggingLevel` set by the client is an MCP logging level.
90+
See the [Logging Levels](#logging-levels) section above for the mapping between MCP and .NET logging levels.
91+
92+
[SetLoggingLevel]: https://modelcontextprotocol.github.io/csharp-sdk/api/ModelContextProtocol.Client.McpClientExtensions.html#ModelContextProtocol_Client_McpClientExtensions_SetLoggingLevel_ModelContextProtocol_Client_IMcpClient_Microsoft_Extensions_Logging_LogLevel_System_Threading_CancellationToken_
93+
94+
[!code-csharp[](samples/client/Program.cs?name=snippet_LoggingLevel)]
95+
96+
Lastly, the client must configure a notification handler for [NotificationMethods.LoggingMessageNotification] notifications.
97+
The following example simply writes the log messages to the console.
98+
99+
[NotificationMethods.LoggingMessageNotification]: https://modelcontextprotocol.github.io/csharp-sdk/api/ModelContextProtocol.Protocol.NotificationMethods.html#ModelContextProtocol_Protocol_NotificationMethods_LoggingMessageNotification
100+
101+
[!code-csharp[](samples/client/Program.cs?name=snippet_LoggingHandler)]

‎docs/concepts/logging/samples/client/LoggingClient.csproj

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
<Project Sdk="Microsoft.NET.Sdk">
2+
3+
<PropertyGroup>
4+
<OutputType>Exe</OutputType>
5+
<TargetFramework>net9.0</TargetFramework>
6+
<ImplicitUsings>enable</ImplicitUsings>
7+
<Nullable>enable</Nullable>
8+
</PropertyGroup>
9+
10+
<ItemGroup>
11+
<PackageReference Include="ModelContextProtocol.Core" Version="0.3.0-preview.3" />
12+
</ItemGroup>
13+
14+
</Project>

‎docs/concepts/logging/samples/client/Program.cs

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
using ModelContextProtocol.Protocol;
2+
using ModelContextProtocol.Client;
3+
using System.Text.Json;
4+
5+
var endpoint = Environment.GetEnvironmentVariable("ENDPOINT") ?? "http://localhost:3001";
6+
7+
var clientTransport = new SseClientTransport(new()
8+
{
9+
Endpoint = new Uri(endpoint),
10+
TransportMode = HttpTransportMode.StreamableHttp,
11+
});
12+
13+
await using var mcpClient = await McpClientFactory.CreateAsync(clientTransport);
14+
15+
// <snippet_LoggingCapabilities>
16+
// Verify that the server supports logging
17+
if (mcpClient.ServerCapabilities.Logging is null)
18+
{
19+
Console.WriteLine("Server does not support logging.");
20+
return;
21+
}
22+
// </snippet_LoggingCapabilities>
23+
24+
// Get the first argument if it was specified
25+
var firstArgument = args.Length > 0 ? args[0] : null;
26+
27+
if (firstArgument is not null)
28+
{
29+
// Set the logging level to the value from the first argument
30+
if (Enum.TryParse<LoggingLevel>(firstArgument, true, out var loggingLevel))
31+
{
32+
// <snippet_LoggingLevel>
33+
await mcpClient.SetLoggingLevel(loggingLevel);
34+
// </snippet_LoggingLevel>
35+
}
36+
else
37+
{
38+
Console.WriteLine($"Invalid logging level: {firstArgument}");
39+
// Print a list of valid logging levels
40+
Console.WriteLine("Valid logging levels are:");
41+
foreach (var level in Enum.GetValues<LoggingLevel>())
42+
{
43+
Console.WriteLine($" - {level}");
44+
}
45+
}
46+
}
47+
48+
// <snippet_LoggingHandler>
49+
mcpClient.RegisterNotificationHandler(NotificationMethods.LoggingMessageNotification,
50+
(notification, ct) =>
51+
{
52+
if (JsonSerializer.Deserialize<LoggingMessageNotificationParams>(notification.Params) is { } ln)
53+
{
54+
Console.WriteLine($"[{ln.Level}] {ln.Logger} {ln.Data}");
55+
}
56+
else
57+
{
58+
Console.WriteLine($"Received unexpected logging notification: {notification.Params}");
59+
}
60+
61+
return default;
62+
});
63+
// </snippet_LoggingHandler>
64+
65+
// Now call the "logging_tool" tool
66+
await mcpClient.CallToolAsync("logging_tool");
67+

‎docs/concepts/logging/samples/server/Logging.csproj

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
<Project Sdk="Microsoft.NET.Sdk.Web">
2+
3+
<PropertyGroup>
4+
<TargetFramework>net9.0</TargetFramework>
5+
<Nullable>enable</Nullable>
6+
<ImplicitUsings>enable</ImplicitUsings>
7+
</PropertyGroup>
8+
9+
<ItemGroup>
10+
<PackageReference Include="ModelContextProtocol.AspNetCore" Version="0.3.0-preview.3" />
11+
</ItemGroup>
12+
13+
</Project>

‎docs/concepts/logging/samples/server/Logging.http

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
@HostAddress = http://localhost:3001
2+
3+
POST {{HostAddress}}/
4+
Accept: application/json, text/event-stream
5+
Content-Type: application/json
6+
7+
{
8+
"jsonrpc": "2.0",
9+
"id": 1,
10+
"method": "initialize",
11+
"params": {
12+
"clientInfo": {
13+
"name": "RestClient",
14+
"version": "0.1.0"
15+
},
16+
"capabilities": {},
17+
"protocolVersion": "2025-06-18"
18+
}
19+
}
20+
21+
###
22+
23+
@SessionId = JCo3W4Q7KA_evyWoFE5qwA
24+
25+
###
26+
27+
POST {{HostAddress}}/
28+
Accept: application/json, text/event-stream
29+
Content-Type: application/json
30+
MCP-Protocol-Version: 2025-06-18
31+
Mcp-Session-Id: {{SessionId}}
32+
33+
{
34+
"jsonrpc": "2.0",
35+
"id": 2,
36+
"method": "tools/call",
37+
"params": {
38+
"name": "logging_tool"
39+
}
40+
}

‎docs/concepts/logging/samples/server/Program.cs

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
using Logging.Tools;
2+
3+
var builder = WebApplication.CreateBuilder(args);
4+
5+
// Add services to the container.
6+
7+
builder.Services.AddMcpServer()
8+
.WithHttpTransport(options =>
9+
options.IdleTimeout = Timeout.InfiniteTimeSpan // Never timeout
10+
)
11+
.WithTools<LoggingTools>();
12+
// .WithSetLoggingLevelHandler(async (ctx, ct) => new EmptyResult());
13+
14+
var app = builder.Build();
15+
16+
app.UseHttpsRedirection();
17+
18+
app.MapMcp();
19+
20+
app.Run();

‎docs/concepts/logging/samples/server/Properties/launchSettings.json

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
{
2+
"$schema": "https://json.schemastore.org/launchsettings.json",
3+
"profiles": {
4+
"http": {
5+
"commandName": "Project",
6+
"dotnetRunMessages": true,
7+
"launchBrowser": false,
8+
"applicationUrl": "http://localhost:3001",
9+
"environmentVariables": {
10+
"ASPNETCORE_ENVIRONMENT": "Development"
11+
}
12+
},
13+
"https": {
14+
"commandName": "Project",
15+
"dotnetRunMessages": true,
16+
"launchBrowser": false,
17+
"applicationUrl": "https://localhost:7207;http://localhost:3001",
18+
"environmentVariables": {
19+
"ASPNETCORE_ENVIRONMENT": "Development"
20+
}
21+
}
22+
}
23+
}

‎docs/concepts/logging/samples/server/Tools/LoggingTools.cs

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
using System.ComponentModel;
2+
using ModelContextProtocol.Protocol;
3+
using ModelContextProtocol.Server;
4+
5+
namespace Logging.Tools;
6+
7+
[McpServerToolType]
8+
public class LoggingTools
9+
{
10+
[McpServerTool, Description("Demonstrates a tool that produces log messages")]
11+
public static async Task<string> LoggingTool(
12+
RequestContext<CallToolRequestParams> context,
13+
int duration = 10,
14+
int steps = 10)
15+
{
16+
var progressToken = context.Params?.ProgressToken;
17+
var stepDuration = duration / steps;
18+
19+
// <snippet_LoggingConfiguration >
20+
ILoggerProvider loggerProvider = context.Server.AsClientLoggerProvider();
21+
ILogger logger = loggerProvider.CreateLogger("LoggingTools");
22+
// </snippet_LoggingConfiguration>
23+
24+
for (int i = 1; i <= steps; i++)
25+
{
26+
await Task.Delay(stepDuration * 1000);
27+
28+
try
29+
{
30+
logger.LogCritical("A critial log message");
31+
logger.LogError("An error log message");
32+
logger.LogWarning("A warning log message");
33+
logger.LogInformation("An informational log message");
34+
logger.LogDebug("A debug log message");
35+
logger.LogTrace("A trace log message");
36+
}
37+
catch (Exception ex)
38+
{
39+
logger.LogError(ex, "An error occurred while logging messages");
40+
}
41+
}
42+
43+
return $"Long running tool completed. Duration: {duration} seconds. Steps: {steps}.";
44+
}
45+
}

‎docs/concepts/logging/samples/server/appsettings.Development.json

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
{
2+
"Logging": {
3+
"LogLevel": {
4+
"Default": "Information",
5+
"Microsoft.AspNetCore": "Warning"
6+
}
7+
}
8+
}

0 commit comments

Comments
 (0)