RalfHuesing.Mcp.Observability 1.0.1

RalfHuesing.Mcp.Observability

A NuGet package that adds unified JSONL tool-call logging and a structured agent feedback channel to any MCP server built on the official ModelContextProtocol SDK.

Why

MCP servers run as stdio processes — they have no built-in logging that survives a binary update. When an LLM agent misbehaves or a tool returns unexpected results, there is usually no trace of what happened.

This package solves that with a single call:

builder.Services
    .AddMcpServer()
    .WithStdioServerTransport()
    .WithToolsFromAssembly()
    .WithObservability();          // ← one line

From that point on:

• Every tools/call is logged to a JSONL file that survives server reinstalls.
• Agents can report issues and feature requests via report_observability_feedback.

What it does

Requirements

• .NET 10 or later
• ModelContextProtocol SDK 2.x (stable)

Installation

dotnet add package RalfHuesing.Mcp.Observability

Quick Start

Standard Integration (Attribute-Based Tool Discovery)

// Program.cs
var builder = Host.CreateApplicationBuilder(args);

// Optional: read options from appsettings.json
var obsOptions = builder.Configuration
    .GetSection("McpObservability")
    .Get<McpObservabilityOptions>()
    ?? new McpObservabilityOptions();   // all defaults = enabled

builder.Services
    .AddMcpServer(options =>
    {
        options.ServerInfo = new() { Name = "MyServer", Version = "1.0.0" };
    })
    .WithStdioServerTransport()
    .WithToolsFromAssembly()
    .WithObservability(obsOptions);

await builder.Build().RunAsync();

Manual ToolCollection Integration

If your MCP server creates tools programmatically via McpServerOptions.ToolCollection, observability works out-of-the-box without manual reflection on internal tools:

var myTool = McpServerTool.Create(
    (Func<string, string>)MyTools.Echo,
    new McpServerToolCreateOptions { Name = "echo" });

builder.Services
    .AddMcpServer(options =>
    {
        options.ServerInfo = new() { Name = "MyServer", Version = "1.0.0" };
        options.ToolCollection = [myTool];
    })
    .WithStdioServerTransport()
    .WithObservability(); // automatically appends report_observability_feedback via post-configure

You can also explicitly attach the feedback tool directly to any McpServerPrimitiveCollection<McpServerTool>:

toolsCollection.AddFeedbackTool(serviceProvider);

Configuration

All settings are optional. Without configuration, everything is enabled and logs go to %LOCALAPPDATA%\RalfHuesing\McpObservability\.

{
  "McpObservability": {
    "Enabled": true,
    "EnableToolCallLogging": true,
    "EnableFeedbackTool": true,
    "EnableResponseLogging": true,
    "MaxResponseLength": 0,
    "ServerName": "CustomServerName",
    "ServerVersion": "1.2.0"
    // "LogDirectory": "D:\\Logs\\Mcp"
  }
}

Diagnostics Service

Inject IMcpObservabilityService anywhere in your application to read current observability state:

public class StatusEndpoint(IMcpObservabilityService observability)
{
    public object GetStatus() => new
    {
        observability.IsEnabled,
        observability.ServerName,
        observability.ServerVersion,
        observability.CurrentLogFilePath,
        observability.ProcessId,
        observability.InstanceId
    };
}

Reading logs while the server is running

Log files are opened with FileShare.ReadWrite. When reading log files while the MCP server is actively writing, open the file with read-write sharing to avoid file-lock exceptions:

using var stream = new FileStream(logFilePath, FileMode.Open, FileAccess.Read, FileShare.ReadWrite);
using var reader = new StreamReader(stream, Encoding.UTF8);

while (await reader.ReadLineAsync() is { } line)
{
    // process JSONL record
}

Log file location

%LOCALAPPDATA%\RalfHuesing\McpObservability\
└── {ServerName}\
    └── {yyyy-MM-dd}\
        └── {ServerName}_{ProcessId}_{InstanceId}.jsonl

Example: AiNetLinter\2026-08-17\AiNetLinter_18432_a1b2c3d4e5f67890.jsonl

JSONL record format

Each line is a self-contained JSON object. All records share these fields:

{
  "schemaVersion": 1,
  "timestamp": "2026-08-17T17:22:01.123Z",
  "recordType": "tool_call",
  "serverName": "AiNetLinter",
  "serverVersion": "1.4.2",
  "processId": 18432,
  "instanceId": "a1b2c3d4e5f67890"
}

tool_call additional fields

The tool_call schema always includes all response fields. When EnableResponseLogging is false, response is null; the response metrics still describe the unlogged tool result.

{
  "toolName": "analyze_code",
  "arguments": { "filePath": "src/Foo.cs" },
  "durationMs": 142,
  "success": true,
  "isErrorResult": false,
  "errorMessage": null,
  "response": "Analysis clean. 0 violations found.",
  "responseLength": 36,
  "responseLines": 1,
  "responseTruncated": false,
  "nonTextContentBlocks": 0
}

feedback additional fields

{
  "feedbackType": "issue",
  "title": "False positive on nullable reference",
  "description": "When analyzing … the tool reported …",
  "relatedTool": "analyze_code",
  "severity": "medium",
  "expectedBehavior": "…",
  "actualBehavior": "…",
  "additionalContext": "…"
}

The feedback tool

report_observability_feedback is automatically registered when EnableFeedbackTool = true. Agents see it as a regular MCP tool.

Report an issue or a feature request about this MCP server. Use this tool whenever something is wrong (bugs, false positives, unexpected results, confusing output) or when a needed capability is missing. After reporting, continue with the best available workaround.

License

MIT — see LICENSE.