C# MCP Server Debugging

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:

``bash dotnet build ` Then restart the MCP server (click Stop → Start in VS Code, or restart dotnet run`).

1. 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

1. Check `mcp.json` points to the correct project path

1. 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

1. Trigger the tool (via Inspector, Copilot, or test client)
2. 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.

1. 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:

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.

Related skills