Skip to content

Commit 72ad781

Browse files
mikekistlermikekistler
committed
Add articles on logging and progress
1 parent 15f8e89 commit 72ad781

22 files changed

+604
-3
lines changed

‎docs/concepts/elicitation/elicitation.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
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

‎docs/concepts/logging/logging.md

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