mcp-csharp-debug

What this skill does

# C# MCP Server Debugging

Run, debug, and interactively test C# MCP servers. Covers local execution, IDE debugging with breakpoints, MCP Inspector for protocol-level testing, and GitHub Copilot Agent Mode integration.

## When to Use

- Running an MCP server locally for the first time
- Configuring VS Code or Visual Studio to debug an MCP server
- Testing tools interactively with MCP Inspector
- Verifying tools appear in GitHub Copilot Agent Mode
- Diagnosing issues: tools not discovered, protocol errors, server crashes
- Setting up `mcp.json` or `.mcp.json` configuration

## Stop Signals

- **No project yet?** → Use `mcp-csharp-create` first
- **Need automated tests?** → Use `mcp-csharp-test`
- **Production deployment issue?** → Use `mcp-csharp-publish`

## Inputs

| Input | Required | Description |
|-------|----------|-------------|
| Project path | Yes | Path to the `.csproj` file or project directory |
| Transport type | Recommended | `stdio` or `http` — detect from `.csproj` if not specified |
| IDE | Recommended | VS Code or Visual Studio — detect from environment if not specified |

**Agent behavior:** Detect transport type by checking the `.csproj` for a `PackageReference` to `ModelContextProtocol.AspNetCore`. If present → HTTP, otherwise → stdio.

## Workflow

### Step 1: Run the server locally

**stdio transport:**
```bash
cd <ProjectDir>
dotnet run
```
The process starts and waits for JSON-RPC messages on stdin. No output on stdout means it's working correctly.

**HTTP transport:**
```bash
cd <ProjectDir>
dotnet run
# Server listens on http://localhost:3001 (or configured port)
```

### Step 2: Generate MCP configuration

Detect the IDE and transport, then create the appropriate config file.

**For VS Code** — create `.vscode/mcp.json`:

stdio:
```json
{
  "servers": {
    "<ProjectName>": {
      "type": "stdio",
      "command": "dotnet",
      "args": ["run", "--project", "<path/to/ProjectFile.csproj>"]
    }
  }
}
```

HTTP:
```json
{
  "servers": {
    "<ProjectName>": {
      "type": "http",
      "url": "http://localhost:3001"
    }
  }
}
```

**For Visual Studio** — create `.mcp.json` at solution root (same JSON structure).

**For detailed IDE-specific configuration** (launch.json, environment variables, secrets), see [references/ide-config.md](references/ide-config.md).

### Step 3: Test with MCP Inspector

The MCP Inspector provides a UI for testing tools, viewing schemas, and inspecting protocol messages.

**stdio server:**
```bash
npx @modelcontextprotocol/inspector dotnet run --project <path/to/ProjectFile.csproj>
```

**HTTP server:**
1. Start your server: `dotnet run`
2. Run Inspector: `npx @modelcontextprotocol/inspector`
3. Connect to `http://localhost:3001`

**For detailed Inspector capabilities, usage, and troubleshooting**, see [references/mcp-inspector.md](references/mcp-inspector.md).

### Step 4: Test with GitHub Copilot Agent Mode

1. Open GitHub Copilot Chat → switch to **Agent** mode
2. Click **Select Tools** (wrench icon) → verify your server and tools are listed
3. Test with a prompt that should trigger your tool
4. Approve tool execution when prompted

**If tools don't appear — troubleshoot tool discovery:**

1. **Rebuild first** — stale builds are the #1 cause:
   ```bash
   dotnet build
   ```
   Then restart the MCP server (click Stop → Start in VS Code, or restart `dotnet run`).

2. **Check attributes and registration:**
   - Verify `[McpServerToolType]` on the class and `[McpServerTool]` on each public method
   - Methods can be `static` or instance (instance types need DI registration)
   - Verify `.WithTools<T>()` or `.WithToolsFromAssembly()` in Program.cs

3. **Check `mcp.json`** points to the correct project path

4. If still not appearing, reference the tool explicitly: `Using #tool_name, do X`

### Step 5: Set up breakpoint debugging

1. Set breakpoints in your tool methods
2. Launch with the debugger:
   - **VS Code:** F5 (requires `launch.json` — see [references/ide-config.md](references/ide-config.md))
   - **Visual Studio:** F5 or right-click project → Debug → Start
3. Trigger the tool (via Inspector, Copilot, or test client)
4. Execution pauses at breakpoints

**Critical:** Build in Debug configuration. Breakpoints won't hit in Release builds.

### Diagnosing Tool Errors

When a tool works standalone but fails through MCP, work through these checks:

1. **Check the MCP output channel** — In VS Code: View → Output → select your MCP server name. Shows protocol errors and server stderr. In Visual Studio: check the Output window for MCP-related messages.
2. **Attach a debugger** — Set a breakpoint in the failing tool method and step through execution (see Step 5). Check for exceptions being swallowed or unexpected parameter values.
3. **Test with MCP Inspector** — Call the tool directly through Inspector to isolate whether the issue is in the tool code or the client integration: `npx @modelcontextprotocol/inspector dotnet run --project <path>`
4. **Check stdout contamination (stdio only)** — Any `Console.WriteLine()` or logging to stdout corrupts the JSON-RPC protocol. Redirect all output to stderr (see Step 6).
5. **Check common culprits:**
   - **Serialization errors** — Return types must be JSON-serializable. Avoid circular references.
   - **DI registration** — Missing service registrations cause runtime exceptions. Check `Program.cs`.
   - **Parameter binding** — Ensure parameter names and types match the tool schema.
   - **Unhandled exceptions** — Wrap tool logic in try-catch and log to stderr or a file.
6. **Enable file logging** — For post-mortem analysis, log to a file:
   ```csharp
   builder.Logging.AddFile("mcp-debug.log"); // or use Serilog/NLog
   ```

### Step 6: Configure logging

**Critical for stdio transport:** Any output to stdout (including `Console.WriteLine`) **corrupts the MCP JSON-RPC protocol** and causes garbled responses or crashes. All logging and diagnostic output must go to stderr.

**stdio transport** — log to stderr only:
```csharp
builder.Logging.AddConsole(options =>
    options.LogToStandardErrorThreshold = LogLevel.Trace);
```

**HTTP transport** — For HTTP transport logging configuration, see [references/ide-config.md](references/ide-config.md).

**In tool methods** — inject `ILogger<T>` via constructor and use `logger.LogDebug()` / `logger.LogError()`. Logging through `ILogger` respects the stderr configuration above.

## Validation

- [ ] Server starts without errors via `dotnet run`
- [ ] MCP Inspector connects and lists all expected tools
- [ ] Tool calls via Inspector return expected results
- [ ] Breakpoints hit when debugging in IDE
- [ ] Tools appear in GitHub Copilot Agent Mode tool list
- [ ] stdio: no logging output on stdout (stderr only)

## Common Pitfalls

| Pitfall | Solution |
|---------|----------|
| Tools not appearing or stale after changes | **Rebuild first:** `dotnet build`, then restart the server. If still missing, verify `[McpServerToolType]` on class, `[McpServerTool]` on methods, and `WithTools<T>()` or `WithToolsFromAssembly()` in Program.cs |
| stdio server produces garbled output | `Console.WriteLine()` or logging is writing to stdout. All output **must** go to stderr. Set `LogToStandardErrorThreshold = LogLevel.Trace` on the console logger |
| HTTP server returns 404 at MCP endpoint | Missing `app.MapMcp()` in Program.cs |
| Breakpoints not hit | Building in Release mode. Rebuild in Debug: `dotnet build -c Debug`, then restart |
| Environment variables not passed to server | Add `"env"` section to `mcp.json`. For secrets in VS Code, use `"${input:var_id}"` syntax |
| MCP Inspector can't connect to HTTP server | Server not running, or wrong port. Check `dotnet run` output for the listening URL |

## Related Skills

- `mcp-csharp-create` — Create a new MCP server project
- `mcp-csharp-test` — Automated tests and evaluations
- `mcp-csharp-publish` — NuGet, Docker, Azure deployment

## Reference Files

- [references/mcp-inspector