You've been staring at an MSBuild binary log for twenty minutes. Somewhere in those 14,000 nodes is the reason your NuGet restore started pulling a different version of System.Text.Json after someone touched a Directory.Build.props three layers deep. You know the answer is in there — the Structured Log Viewer has it — but finding it means expanding tree nodes, searching for property evaluations, and cross-referencing import chains manually. It's the kind of work that makes you question your career choices.

Microsoft's new Binlog MCP Server changes the equation. Instead of navigating a tree yourself, you describe what you're looking for in plain English, and your AI assistant queries the binlog directly through a set of specialised tools. It parses .binlog files and exposes 38 MCP tools covering build failure investigation, property tracing, performance analysis, and build comparison. Think of it as giving your AI assistant the same powers as the Structured Log Viewer — but with the ability to correlate findings and explain them back to you.

The server shipped in June 2026 as part of the dotnet-msbuild plugin in the dotnet/skills marketplace. It's available for Visual Studio 17.14+, VS Code, GitHub Copilot CLI, and Claude Code. It's still in preview, but it's already capable enough to change how you debug builds.

Generating a binary log

Before you can query anything, you need a binary log. Add /bl to any dotnet build command:

terminal 
dotnet build /bl
dotnet build /bl:my-investigation.binlog
dotnet test /bl
dotnet pack /bl

The default filename is msbuild.binlog in the project root. Binary logs capture everything: every property evaluation, every target invocation, every task execution, file imports, item groups, and even embedded source files. They're comprehensive by design — which is precisely why they're so hard to read manually.

// WARNING

Binary logs can contain sensitive information including environment variables, source code, and file paths. Treat them with the same care you'd give a memory dump. Don't commit them to source control or share them publicly.

Setting up the server

The simplest route is the dotnet-msbuild plugin, which bundles the Binlog MCP Server alongside curated skills and agents for build investigation.

Visual Studio 17.14+: Install the dotnet-msbuild plugin. The MCP server is discovered automatically when GitHub Copilot enters Agent mode.

VS Code: Add the server to .vscode/mcp.json:

.vscode/mcp.json 
{
  "servers": {
    "binlog-mcp": {
      "type": "stdio",
      "command": "dotnet",
      "args": ["tool", "run", "Microsoft.AITools.BinlogMcp"]
    }
  }
}

If you want to pre-load a specific binlog (useful when you always investigate the same build output), pass it as an argument:

.vscode/mcp.json 
{
  "servers": {
    "binlog-mcp": {
      "type": "stdio",
      "command": "dotnet",
      "args": [
        "tool", "run", "Microsoft.AITools.BinlogMcp",
        "--", "--binlog", "msbuild.binlog"
      ]
    }
  }
}

Terminal-based assistants (Claude Code, Copilot CLI): Install from the marketplace directly:

terminal 
/plugin marketplace add dotnet/skills
/plugin install dotnet-msbuild@dotnet-agent-skills

The tool surface

The server exposes 38 tools across six categories. You don't need to memorise them — your AI assistant picks the right ones based on your question — but understanding the categories helps you ask better questions.

Build investigation

The core diagnostic tools handle the most common scenario: something broke and you want to know why.

Properties and evaluation

When a build behaves unexpectedly, the culprit is almost always a property that got the wrong value. These tools trace where values come from.

Items and dependencies

Performance analysis

Slow builds are death by a thousand cuts. These tools identify where the time goes.

Build comparison

Structural exploration

Investigating a build failure in practice

Here's what a real investigation looks like. Your CI pipeline fails with a cryptic error about a missing type. Instead of downloading the binlog and opening the Structured Log Viewer, you ask your assistant:

"Why did my build fail? The binlog is at artifacts/build.binlog."

The assistant calls binlog_overview to get the high-level picture, then binlog_errors to pull the actual errors with context. It might find something like:

error CS0246: The type or namespace name 'JsonSerializerContext' could not be found
  Project: src/Api/Api.csproj
  Target: CoreCompile
  Task: Csc
  File: src/Api/Serialisation/AppJsonContext.cs(12,34)

On its own, that error is straightforward. But the interesting question is why — this compiled fine yesterday. So you follow up:

"Why can't it find JsonSerializerContext? What version of System.Text.Json is this project using?"

The assistant calls binlog_items to check the resolved PackageReference and finds the project is pulling System.Text.Json 8.0.0 instead of 9.0.0. Then it calls binlog_explain_property to trace where the version override is coming from and discovers a Directory.Packages.props higher in the tree pinned an older version.

That's a five-minute investigation instead of a twenty-minute one.

Tracing property origins

The binlog_explain_property tool deserves special attention because it solves the hardest debugging problem in MSBuild: understanding why a property has a specific value.

MSBuild properties can be set in your project file, in Directory.Build.props, in imported .targets files, via environment variables, through global properties passed on the command line, or by tasks during execution. A single property might be set and overridden half a dozen times before reaching its final value.

When you ask "Why is OutputPath set to bin/Release/net11.0/linux-x64/?", the tool walks the evaluation chain and reports every assignment, in order:

  1. Default in SDK: bin/$(Configuration)/$(TargetFramework)/
  2. Override in Directory.Build.props: adds $(RuntimeIdentifier)/ suffix
  3. Final value after evaluation: bin/Release/net11.0/linux-x64/

This kind of trace is possible with the Structured Log Viewer, but it requires you to know where to look. The MCP server lets you ask the question directly.

Finding performance bottlenecks

Slow builds rarely have a single cause. The performance tools help you systematically find where time is being spent.

"My solution build takes 4 minutes. What's the bottleneck?"

The assistant calls binlog_expensive_projects and finds that Tests.Integration.csproj takes 95 seconds — a quarter of the total build time. Then binlog_expensive_targets reveals that the ResolveAssemblyReference target accounts for 40 seconds of that, and binlog_expensive_analyzers shows a third-party analyser consuming 18 seconds per project across 12 projects.

// TIP

Run binlog_incremental_analysis regularly. Non-incremental targets are a common source of unnecessary rebuild time, and they're easy to miss because the build still succeeds — it just takes longer than it should.

Comparing builds

The binlog_compare tool is particularly powerful for debugging regressions. Generate a binlog from a known-good commit and another from the broken one:

terminal 
git stash
dotnet build /bl:good.binlog
git stash pop
dotnet build /bl:bad.binlog

Then ask your assistant to compare them:

"Compare good.binlog and bad.binlog. What changed in properties and package versions?"

The tool diffs the two builds and surfaces differences like a property that changed value, a package that was upgraded, or a new import that appeared. This is far faster than manually comparing two builds in separate Structured Log Viewer windows.

Using it in CI

The Binlog MCP Server is not limited to local development. Microsoft's testfx repository demonstrates running it in GitHub Actions using the Agentic Workflows feature. When a PR build fails, an agent automatically opens the binlog, diagnoses the failure, and posts the root cause as a PR comment.

The containerised deployment mounts the binlog read-only:

.github/workflows/build-analysis.yml 
mcp-servers:
  binlog-mcp:
    container: "mcr.microsoft.com/dotnet-buildtools/prereqs:azurelinux-3.0-binlog-mcp-amd64"
    mounts:
      - "/tmp/build.binlog:/data/build.binlog:ro"
    allowed: ["*"]

Microsoft's internal evaluation showed a 13% improvement in diagnostic accuracy and 44% faster resolution times compared to a baseline without the MCP tools. Input token consumption also dropped by 10% because the structured tools return focused data instead of raw log dumps.

The search DSL

The binlog_search tool supports the same query syntax as the Structured Log Viewer desktop app. This is worth learning because it's significantly more powerful than plain-text search.

Filter by node type:

Hierarchical scoping:

These queries are passed directly to the server and executed against the binlog's structured data, making them fast even on large builds.

Common pitfalls

Forgetting /bl in CI. Binary log generation is not on by default. If your CI pipeline doesn't produce binlogs, you can't analyse failures after the fact. Add /bl to your build commands in CI — the overhead is minimal and the diagnostic value is substantial.

Binlog size surprises. Large solutions can produce binlogs exceeding 100 MB. The MCP server handles them fine, but if you're storing them as CI artefacts, set a retention policy. A week's worth of binlogs from a busy repository adds up quickly.

Conflating the community tool with the official one. The open-source baronfel.binlog.mcp package (by Chet Husk, a member of the .NET SDK team) predates the official Microsoft.AITools.BinlogMcp. The official version exposes 38 tools compared to the community version's smaller set. Both use the same underlying MSBuild.StructuredLogger library, but the official version includes additional skills, agents, and CI integration support through the dotnet-msbuild plugin.

Not using binlog_explain_property enough. Most developers reach for binlog_search first, but binlog_explain_property is almost always the faster path when the problem is a property with an unexpected value. It gives you the full evaluation chain without any manual correlation.

Telemetry is on by default. The server collects anonymised usage data (tool names, latency, result sizes). No binlog content, file paths, or error messages are transmitted — filenames are HMAC-SHA256 hashed. If your organisation's policy requires explicit consent, opt out with the DOTNET_CLI_TELEMETRY_OPTOUT environment variable.

Summary