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

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.

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:

Start your server:
```
dotnet run
```
Run Inspector:
```
npx @modelcontextprotocol/inspector
```
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

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

If tools don't appear — troubleshoot tool discovery:

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
```
).
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
Check
mcp.json
points to the correct project path
If still not appearing, reference the tool explicitly:
```
Using #tool_name, do X
```

Step 5: Set up breakpoint debugging

Set breakpoints in your tool methods
Launch with the debugger:
- VS Code: F5 (requires
```
launch.json
```
  — see references/ide-config.md)
- Visual Studio: F5 or right-click project → Debug → Start
Trigger the tool (via Inspector, Copilot, or test client)
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:

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.
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.
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>
```
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).
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.
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.

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

mcp-csharp-debug

NPX Install

Tags

SKILL.md Content

C# MCP Server Debugging

When to Use

Stop Signals

Inputs

Workflow

Step 1: Run the server locally

Step 2: Generate MCP configuration

Step 3: Test with MCP Inspector

Step 4: Test with GitHub Copilot Agent Mode

Step 5: Set up breakpoint debugging

Diagnosing Tool Errors

Step 6: Configure logging

Validation

Common Pitfalls

Related Skills

Reference Files

More Info