diagnostics-mcp

.NET Diagnostics MCP

Trigger On

• The user asks to install or use dotnet-diagnostics-mcp for .NET performance investigation.
• The user asks: "Profile all unit tests and identify bottlenecks in the code tested."
• An MCP-connected agent needs runtime evidence for CPU hotspots, allocation pressure, GC pauses, or waiting in a .NET application.

Use this skill for this MCP server's workflow. Use the test framework's guidance for assertions and test authoring, and a benchmark workflow when the question needs precise per-operation timing.

Install and Connect

dotnet tool install -g dotnet-diagnostics-mcp
# If already installed:
dotnet tool update -g dotnet-diagnostics-mcp
dotnet tool list -g

Register dotnet-diagnostics-mcp with arguments ["--stdio"] in the client's native MCP settings, then reload its MCP connection. The client starts and owns the server subprocess; local stdio needs no HTTP daemon or bearer token. Ensure the client can resolve the global-tool command on PATH.

For example, Claude Desktop / Cursor-style configuration:

{
  "mcpServers": {
    "dotnet-diagnostics": {
      "command": "dotnet-diagnostics-mcp",
      "args": ["--stdio"]
    }
  }
}

Check tools/list for inspect_process, collect_batch, collect_sample, collect_events, and query_snapshot. Installing the tool alone does not connect it to the current AI session. If startup rejects symlink/reparse-point paths, set the server's MCP_ARTIFACT_ROOT environment variable to an existing writable directory whose full path has no symlinks; see tool patterns.

Workflow

1. Identify the requested workload, runtime, test runner, and unit-test projects. Build Release binaries with matching PDBs before the measured run. Keep build/restore time separate from test execution.
2. For all-unit-test requests, follow test profiling: inventory projects, retain normal test parallelism, start the suite, and discover the actual test host or application process by command line. Record every relevant PID and its capture window.
3. Resolve an explicit processId with inspect_process(view="list", commandLineContains=...). Use view="info" to verify its identity. For a long-lived app, view="triage" can choose the next collector; avoid spending a short test host's lifetime on preliminary captures.
4. Capture CPU and managed allocations together with collect_batch; optionally add GC and counters, up to four entries. Use depth="compact" and read the returned digest and per-entry errors before querying handles.
5. Follow the hot path into the code under test. Separate product methods from runner, fixture, mocking, assertion, JIT, and profiler overhead. Use tool patterns for collector selection and evidence limits.
6. Reproduce a suspected hotspot with the runner's native test filter, preserving unrelated parallel execution. Compare equal workload, runtime, configuration, concurrency, and capture duration. Change code only within the user's requested scope, then rerun correctness checks and the same profile.