mcp-csharp-debug

name	mcp-csharp-debug
description	Run and debug C# MCP servers locally. Covers IDE configuration, MCP Inspector testing, GitHub Copilot Agent Mode integration, logging setup, and troubleshooting. USE FOR: running MCP servers locally with dotnet run, configuring VS Code or Visual Studio for MCP debugging, testing tools with MCP Inspector, testing with GitHub Copilot Agent Mode, diagnosing tool registration issues, setting up mcp.json configuration, debugging MCP protocol messages, configuring logging for stdio and HTTP servers. DO NOT USE FOR: creating new MCP servers (use mcp-csharp-create), writing automated tests (use mcp-csharp-test), publishing or deploying to production (use mcp-csharp-publish).
license	MIT

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:

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:

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:

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

HTTP:

{
  "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.

Step 3: Test with MCP Inspector

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

stdio server:

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.

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:

   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)
   • 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:

   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:

builder.Logging.AddConsole(options =>
    options.LogToStandardErrorThreshold = LogLevel.Trace);

HTTP transport — For HTTP transport logging configuration, see 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.md — Detailed MCP Inspector usage: installation, connecting to servers, feature walkthrough, troubleshooting. Load when: user needs detailed Inspector guidance or is having connection issues.
• references/ide-config.md — Complete VS Code and Visual Studio configuration: mcp.json templates, launch.json, environment variables, conditional breakpoints. Load when: setting up IDE debugging or configuring environment-specific settings.

More Info

• MCP Inspector — Interactive debugging tool for MCP servers
• VS Code MCP documentation — Configuring MCP servers in VS Code