DotnetDiagnosticsMcp.Server
0.2.1
dotnet tool install --global DotnetDiagnosticsMcp.Server --version 0.2.1
dotnet new tool-manifest
dotnet tool install --local DotnetDiagnosticsMcp.Server --version 0.2.1
#tool dotnet:?package=DotnetDiagnosticsMcp.Server&version=0.2.1
nuke :add-package DotnetDiagnosticsMcp.Server --version 0.2.1
dotnet-diagnostics-mcp
Status: MCP server functional with 20 diagnostic tools, two transports (HTTP + stdio), and 6 curated investigation prompts. End-to-end tests pass on Linux + Windows. See
docs/for the tool reference and investigation playbooks.
An MCP server that lets an LLM perform on-demand performance diagnostics on running .NET 10 applications — locally or in Kubernetes — without any modification to the target app.
It builds on the existing .NET diagnostics pipeline (Microsoft.Diagnostics.NETCore.Client
- EventPipe + ClrMD) and exposes it as MCP tools over either Streamable HTTP (sidecar / shared dev instance) or stdio (MCP client spawns the server as a subprocess), so any MCP-aware client (Claude Desktop, Copilot CLI, custom agents, ...) can drive an investigation.
Goals
- Zero changes to the target app for CoreCLR (JIT/R2R) processes
- Cross-platform Linux + Windows (containers as a first-class citizen)
- Graceful NativeAOT support — tools that can't work on AOT (CPU sampling, gcdump)
return a clear
not_supportedinstead of crashing - LLM-friendly outputs — every tool returns summarized JSON (top-N hotspots, aggregates),
not raw
.nettraceblobs
Repository layout
src/
DotnetDiagnosticsMcp.Core/ # diagnostic primitives (process discovery, EventPipe sessions, parsing)
DotnetDiagnosticsMcp.Server/ # ASP.NET Core host + MCP tools + bearer auth
samples/
CoreClrSample/ # plain ASP.NET Core webapi used as a target for testing
NativeAotSample/ # webapi with PublishAot=true and EventSourceSupport=true
tests/
DotnetDiagnosticsMcp.Core.Tests/
DotnetDiagnosticsMcp.Server.IntegrationTests/
Tools at a glance
| Tool | Purpose |
|---|---|
list_dotnet_processes / get_process_info |
Discover .NET processes via diagnostic IPC |
get_diagnostic_capabilities |
Detect CoreCLR vs NativeAOT and what's usable |
get_container_signals |
Linux cgroup v2: CPU throttling, memory pressure, OOM kills, PSI |
snapshot_counters |
EventCounters over a window (cpu, memory, requests, ...) |
collect_cpu_sample / get_call_tree |
Top-N CPU hotspots (inclusive/exclusive) + on-demand caller→callee tree |
collect_off_cpu_sample / query_off_cpu_snapshot |
Where threads block (futex / IO / sleep) — Linux perf backend |
collect_exceptions |
Managed exceptions thrown in a window, aggregated by type |
collect_gc_events |
GC pauses + per-generation counts |
collect_event_source / query_collection |
Generic EventSource passthrough (HTTP, Kestrel, custom) + re-project artifacts |
collect_thread_snapshot / query_thread_snapshot |
Managed thread states + SyncBlock lock graph drilldown |
inspect_live_heap / inspect_dump / query_heap_snapshot |
Top retained types + retention paths + roots, live or from a dump |
collect_process_dump |
Write a Mini / Triage / WithHeap / Full dump to disk |
start_investigation |
Structured plan (cold / warm / hypothesis) before any collector runs |
export_investigation_summary / compare_to_baseline |
Portable JSON memory; LLM persists, diffs across deploys |
get_collection_status / cancel_collection |
Background-job lifecycle for long collections |
Full schemas and return shapes: docs/tool-reference.md.
Common investigation recipes: docs/investigation-playbooks.md.
Client setup (C# SDK, GUI clients, curl): docs/client-setup.md.
Kubernetes sidecar: deploy/k8s/README.md.
Azure (App Service + Container Apps) recipes: deploy/azure/README.md.
processIdis optional everywhere. When the sidecar only sees one .NET process the server auto-resolves it and stamps a capability digest on every response (resolvedProcess.autoResolved = true), so thelist_dotnet_processes→get_diagnostic_capabilitiesopener can be skipped entirely. On ambiguity / nothing visible you get a structured error with the candidate list inline. See issue #42.
Prompts (curated playbooks). The server also exposes 6 MCP Prompts that pre-package the recipes in
docs/investigation-playbooks.md:diagnose-high-latency,diagnose-memory-growth,diagnose-5xx-errors,diagnose-slow-outbound-http,triage-nativeaot,diagnose-safely-in-prod. Every input is optional, every body is annotated for the LLM (audience: ["assistant"]). See issue #44 and the Prompts section indocs/tool-reference.md.
Install (consumers)
Three distributions of the MCP server, all wire-compatible. Pick whichever fits your environment best — see docs/consumer-install.md for the full walkthrough including supervisor templates (systemd, Windows Scheduled Task, launchd) and mcp-config.json snippets.
# .NET global tool (requires .NET 10 SDK)
dotnet tool install -g DotnetDiagnosticsMcp.Server
dotnet-diagnostics-mcp --urls http://127.0.0.1:8787
# Container (no SDK needed; predictable filesystem)
docker run -d --restart unless-stopped -p 127.0.0.1:8787:8787 \
-e MCP_BEARER_TOKEN=$(openssl rand -hex 32) \
ghcr.io/pedrosakuma/dotnet-diagnostics-mcp:latest
# For off-CPU sampling (collect_off_cpu_sample) or NativeAOT CPU sampling, use the
# `-perf` variant which ships linux-perf preinstalled:
# ghcr.io/pedrosakuma/dotnet-diagnostics-mcp:latest-perf
# (Requires CAP_PERFMON or perf_event_paranoid <= -1 on the host.)
# Or grab a self-contained single-file binary for your OS/arch from the Releases page.
Transports — pick by deployment shape
- stdio (recommended for local dev with Copilot CLI / Claude Desktop / Cursor): the
MCP client spawns
dotnet-diagnostics-mcp --stdioas a subprocess and talks JSON-RPC over stdio. The client owns the process lifecycle, sodotnet tool update -g …is picked up automatically on the next client reload — no stale daemons. - HTTP (sidecar in K8s, shared dev host, multi-client): long-lived daemon on
127.0.0.1:8787(or a sidecar container). UseMCP_BEARER_TOKEN+ optionallyDOTNET_DIAGNOSTICS_MCP_AUTO_RESTART=trueso the built-inStaleBinaryWatcherasks the supervisor (systemd /docker --restart=always/ K8s) to recycle the process when the on-disk image MVID drifts. Seedocs/client-setup.mdfor the fullmcp-config.jsonsnippets per client.
🐧 Linux: on Debian/Ubuntu/WSL/Codespaces the
kernel.yama.ptrace_scope=1default blocks the four ClrMD-backed tools (collect_thread_snapshot,inspect_live_heap,inspect_dumpagainst a live PID,collect_process_dump). See Consumer install → § 1.5 Linux: enabling ClrMD-backed tools (ptrace) for the one-line fix per distribution. EventPipe-only tools (counters, CPU sample, exceptions, GC, EventSources) work out of the box.
Joint with dotnet-assembly-mcp (recommended for handoff resolution)
For the full handoff story — MethodIdentity / TypeIdentity resolving to
decompiled bodies, call graphs, attributes, type hierarchy — run both servers
together with the joint compose file:
export ASSEMBLIES_DIR=/abs/path/to/your/published/binaries
docker compose -f deploy/docker-compose.yml up -d
# diagnostics: http://localhost:8787/mcp
# assembly: http://localhost:8788/mcp
The same docker-compose.yml ships in
pedrosakuma/dotnet-assembly-mcp:deploy/docker-compose.yml
— bring it up from either checkout. Set MCP_BEARER_TOKEN on the host to gate
both servers with one shared token.
Health probe used by every supervisor (and the container's HEALTHCHECK):
dotnet-diagnostics-mcp --health-check --urls http://127.0.0.1:8787
The companion pedrosakuma/dotnet-assembly-mcp is optional in a dev environment after #28 — MethodIdentity payloads now carry a resolved SourceLocation whenever a PDB is reachable on the diagnostics box, so the LLM can open File:Line directly. The partner is the right call for stripped binaries, decompilation, and call-graph queries.
Build & test
dotnet build
dotnet test
Requires the .NET 10 SDK (pinned in global.json).
Authentication
The HTTP transport requires a Bearer token on every request to /mcp/* (the /health endpoint is open). The stdio transport does not use a token — the spawning client is already trusted at the OS level.
- Set
MCP_BEARER_TOKENto use a fixed token (recommended). - If unset, an ephemeral token is generated at startup and printed in the logs.
export MCP_BEARER_TOKEN="$(openssl rand -hex 32)"
dotnet run --project src/DotnetDiagnosticsMcp.Server
Contributor setup (shared dev instance)
Looking for a consumer install? See the Install section above.
The HTTP transport is multi-client, so a single shared MCP instance on 127.0.0.1:8787 serves any number of concurrent clients (multiple gh copilot sessions, editors, etc). Use the lifecycle wrapper for an idempotent, deterministic local setup against the current source checkout:
scripts/local-mcp.sh start # builds (Release) + starts in background; idempotent
scripts/local-mcp.sh status
scripts/local-mcp.sh logs -f
scripts/local-mcp.sh restart
scripts/local-mcp.sh stop
The script pins URL (LOCAL_MCP_URL, default http://127.0.0.1:8787) and bearer
token (MCP_BEARER_TOKEN, default demo-local-token-2026), uses
--no-launch-profile so launchSettings.json can't silently override the port,
and stores its PID at /tmp/dotnet-diagnostics-mcp.pid and logs at
/tmp/dotnet-diagnostics-mcp.log (overridable via LOCAL_MCP_PIDFILE /
LOCAL_MCP_LOGFILE). Pair with the matching entry in ~/.copilot/mcp-config.json:
{
"mcpServers": {
"dotnet-diagnostics": {
"type": "http",
"url": "http://127.0.0.1:8787/mcp",
"headers": { "Authorization": "Bearer demo-local-token-2026" }
}
}
}
There is also a dedicated local-mcp launch profile for one-off foreground runs:
dotnet run --project src/DotnetDiagnosticsMcp.Server --launch-profile local-mcp.
Roadmap
See docs/ (to be filled in) and the planning notes in the session workspace.
Phases:
- ✅ Foundation
- ✅ Core diagnostics (process discovery, capability detection, counters, CPU sampling)
- ✅ MCP server MVP wired to Core
- ✅ Advanced tools (GC, exceptions, custom EventSources, dumps)
- ✅ Kubernetes sidecar topology + manifests (see
deploy/k8s/) - ✅ Documentation polish (tool reference, investigation playbooks, client setup)
- ✅ Cloud-native integrations: Azure App Service + Container Apps (see
deploy/azure/). AWS / GCP tracked as follow-up issues. - ⏳ Future: NativeAOT publish, AWS ECS / Fargate, GCP Cloud Run.
License
TBD.
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. |
This package has no dependencies.
| Version | Downloads | Last Updated |
|---|