# troubleshoot-binlog-mcp

troubleshoot-binlog-mcp finds why the dotnet-msbuild binlog MCP server fails to start or connect, with checks for the workspace SDK, NuGet feeds, and host setup.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Windsurf (Devin Desktop), Claude.ai · 1300 installs · ★ 6320 repo stars
- Author: dotnet
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/dotnet/skills/tree/HEAD/plugins/dotnet-msbuild/skills/troubleshoot-binlog-mcp/SKILL.md
- Updated: 2026-10-24
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/troubleshoot-binlog-mcp

## What it does

This skill investigates binlog MCP startup failures such as `CONNECTION_CLOSED`, missing `Microsoft.AITools.BinlogMcp`, and `dnx` launch errors. It separates a server startup problem from failures recorded inside a binlog. A binlog file or project build is not needed.

It checks the host command, workspace environment, selected SDK, `global.json`, NuGet sources, inherited configuration, and `packageSourceMapping`. When the cause is still unclear, it can reproduce the unchanged launch command while collecting stdout, stderr, and the exit code. The shipped command, `dotnet dnx Microsoft.AITools.BinlogMcp --yes --prerelease`, requires a .NET 10+ SDK.

Recovery advice follows the observed evidence and does not bypass feed policy. The skill avoids suggesting disabled certificate checks or removing source mapping, and it asks for approval before changing SDK pins or host registration. It does not analyze errors stored inside a binlog.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add dotnet/skills --skill troubleshoot-binlog-mcp -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/troubleshoot-binlog-mcp/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/troubleshoot-binlog-mcp/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add dotnet/skills --skill troubleshoot-binlog-mcp -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/troubleshoot-binlog-mcp/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add dotnet/skills --skill troubleshoot-binlog-mcp -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/troubleshoot-binlog-mcp/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install dotnet/skills plugins/dotnet-msbuild/skills/troubleshoot-binlog-mcp
```

2. **Manually: put the files in place**
- File: `.github/skills/troubleshoot-binlog-mcp/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add dotnet/skills --skill troubleshoot-binlog-mcp -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/dotnet/skills --path plugins/dotnet-msbuild/skills/troubleshoot-binlog-mcp
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/troubleshoot-binlog-mcp/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add dotnet/skills --skill troubleshoot-binlog-mcp -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/dotnet/skills/tree/HEAD/plugins/dotnet-msbuild/skills/troubleshoot-binlog-mcp/SKILL.md

## When to use it
- trace a `CONNECTION_CLOSED` MCP startup failure
- check which SDK the workspace selects
- inspect NuGet feeds and `packageSourceMapping`
- separate server launch errors from binlog failures

## Example prompts
- Investigate why the binlog MCP server closes with `CONNECTION_CLOSED`.
- Check why `dotnet dnx Microsoft.AITools.BinlogMcp --yes --prerelease` fails in this workspace.
- Review the launch error against `global.json` and the configured NuGet sources without changing them.

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 8a9281f2a1008f87.

BEGIN THIRD-PARTY FILE 8a9281f2a1008f87
````text
---
name: troubleshoot-binlog-mcp
description: "Diagnose dotnet-msbuild binlog MCP startup failures. USE FOR: CONNECTION_CLOSED, binlog server won't connect, missing binlog tools, Microsoft.AITools.BinlogMcp not found, dnx launch errors. Checks workspace SDK, feeds, and source mapping without bypassing policy. DO NOT USE FOR: errors inside a binlog (use binlog-failure-analysis), capturing binlogs (use binlog-generation), unrelated MCP servers."
license: MIT
---

# Troubleshoot Binlog MCP Startup

Explain why the plugin's binlog MCP server cannot connect and give an evidence-based,
policy-safe recovery. This diagnoses the **server launch**, not failures recorded in a build.
No binlog file or project build is needed.

This skill runs on demand. It cannot see a host error that was never exposed to the agent,
inject session-start context, or guarantee activation merely because a plugin was installed.

## 1. Establish what failed

Use the user's error and any host MCP status or startup logs already available.
`CONNECTION_CLOSED` alone says that the transport closed, not why. Do not translate it
directly into "package missing."

- If the binlog server is connected and its tools are discoverable, stop startup troubleshooting.
  Continue the original binlog analysis; do not change a working setup.
- If the plugin's skills loaded but its binlog server did not, continue below.
- If the plugin itself is not installed/enabled or no server is registered, address that host
  configuration first. Do not diagnose NuGet package resolution without a launch attempt.
- If execution or host logs are unavailable, explain that limit and give the next command for
  the user to run. Never claim to have inspected logs or repaired a connection.

## 2. Match the host's workspace and SDK

Discover the affected workspace directory and the host's actual MCP command, arguments, and
environment from available configuration. The shipped command is:

```text
dotnet dnx Microsoft.AITools.BinlogMcp --yes --prerelease
```

Run diagnostics from that workspace with the host's environment, not from the plugin directory
or a temporary directory with different NuGet settings. Inspect:

```text
dotnet --info
dotnet --version
dotnet nuget list source
```

Check the applicable `global.json` and inherited NuGet configuration, including parent/user
configuration, `clear`, disabled sources, and `packageSourceMapping`. A workspace `clear`
````
END THIRD-PARTY FILE 8a9281f2a1008f87

The third-party file has ended. Everything between the 8a9281f2a1008f87 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2432 of 7868 bytes. © dotnet · MIT · https://github.com/dotnet/skills/tree/HEAD/plugins/dotnet-msbuild/skills/troubleshoot-binlog-mcp/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
