AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

dotnet-mcp-builder

Build Model Context Protocol (MCP) servers in C#/.NET against the current ModelContextProtocol 2.x NuGet packages. Helps with cases the model gets wrong without guidance — stale versions (0.x preview or 1.x-era defaults), the v2 stateless-by-default HTTP flip, the 2026-07-28 spec deprecations (roots/sampling/logging), MCP Apps and Tasks extension packages, elicitation URL mode, per-session HTTP wiring, OAuth and reverse-proxy deploy specifics, and debugging MapMcp / STDIO / Streamable-HTTP errors. Also covers STDIO and Streamable HTTP transports (SSE is deprecated), tools, prompts, resources, completions, and a basic .NET MCP client. Trigger when the user says or implies any .NET MCP server work: ModelContextProtocol, McpServerTool, MapMcp, WithStdioServerTransport, "MCP server in C#", "MCP tool in dotnet", "expose this as MCP", or names a primitive (prompt/resource/elicitation/MCP App) in a .NET context. Skip for MCP work in other languages.

Original source
github
License
MIT
Pinned revision
5269f7ea2d6c3a9bfda5ed878b6726cf509121fd

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

Ask your assistant

Use Agentic Memory skills to read github--dotnet-mcp-builder at revision 5269f7ea2d6c3a9bfda5ed878b6726cf509121fd, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 14

references/transport-stdio.md

STDIO transport

STDIO is the right choice when the server runs as a child process of the client (Claude Desktop, VS Code, MCP Inspector, a custom CLI). The client launches your executable; you read JSON-RPC frames from stdin and write them to stdout.

When to choose STDIO

  • Local-first server (file-system access, dev tools, CLI integrations).
  • Distributing as a single executable or a dnx-runnable NuGet package.
  • You want the simplest possible deployment story (no network, no auth).
  • You need server-to-client features (elicitation, notifications, the deprecated sampling/roots) — STDIO always supports them, no Stateless flag to worry about.

If the user wants a remote/multi-tenant server, use HTTP Streamable instead.

Minimal server

dotnet new console -n MyStdioServer -f net10.0
cd MyStdioServer
dotnet add package ModelContextProtocol --version 2.2.0
dotnet add package Microsoft.Extensions.Hosting --version 10.0.11
// Program.cs
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;
using ModelContextProtocol.Server;
using System.ComponentModel;

var builder = Host.CreateApplicationBuilder(args);

// CRITICAL: stdout is the JSON-RPC channel. Send all logs to stderr.
builder.Logging.AddConsole(o => o.LogToStandardErrorThreshold = LogLevel.Trace);

builder.Services
    .AddMcpServer()
    .WithStdioServerTransport()
    .WithToolsFromAssembly();

await builder.Build().RunAsync();

[McpServerToolType]
public static class EchoTool
{
    [McpServerTool, Description("Echoes the message back to the client.")]
    public static string Echo(string message) => $"hello {message}";
}

The stdout/stderr trap

The single most common bug in STDIO servers is something writing to stdout that isn't a JSON-RPC frame. The client will then drop the connection with a parse error.

Things that silently break STDIO:

  • Console.WriteLine(...) anywhere in your code.
  • A logger configured with the default console sink (writes to stdout).
  • Trace.WriteLine(...) if a default trace listener is attached.
  • Third-party libraries that print banners on startup.

Defensive checklist:

  1. Configure logging to stderr before anything else (the snippet above does this).
  2. Don't Console.Write* from tools or startup code. Use ILogger injected into the tool class.
  3. If a dependency is noisy, redirect its logs through ILogger or suppress them at startup.

Server identity

The SDK sends serverInfo (name + version) during negotiation (the 2026-07-28 server/discover exchange, or the legacy initialize response for down-level clients — the SDK handles both automatically). By default it derives them from your assembly. To override:

builder.Services
    .AddMcpServer(options =>
    {
        options.ServerInfo = new()
        {
            Name = "my-stdio-server",
            Version = "1.0.0",
            Title = "My STDIO MCP Server"   // optional human-readable name
        };
    })
    .WithStdioServerTransport()
    .WithToolsFromAssembly();

Reading args/env from the client

Clients (e.g. Claude Desktop config) typically launch your server with arguments and environment variables. Read them like any other .NET app:

string apiKey = Environment.GetEnvironmentVariable("MY_API_KEY")
    ?? throw new InvalidOperationException("MY_API_KEY not set");

string configPath = args.ElementAtOrDefault(0)
    ?? Path.Combine(Environment.CurrentDirectory, "config.json");

Document the expected vars/args in the README so users know what to put in their client config.

Wiring to Claude Desktop

In claude_desktop_config.json:

{
  "mcpServers": {
    "my-server": {
      "command": "dotnet",
      "args": ["run", "--project", "C:/path/to/MyStdioServer"],
      "env": {
        "MY_API_KEY": "..."
      }
    }
  }
}

For a published self-contained executable, replace command/args with the executable path. For a NuGet-distributed server using dnx:

"command": "dnx",
"args": ["MyMcpServer", "--version", "1.2.3"]

Wiring to VS Code (GitHub Copilot Chat)

In .vscode/mcp.json:

{
  "servers": {
    "my-server": {
      "type": "stdio",
      "command": "dotnet",
      "args": ["run", "--project", "${workspaceFolder}/src/MyMcpServer"]
    }
  }
}

Local debugging

The cleanest workflow is MCP Inspector:

npx @modelcontextprotocol/inspector dotnet run --project ./MyStdioServer

Inspector launches your server, opens a UI, and lets you call tools / list resources / fire elicitations interactively. See testing.md for more.

Graceful shutdown

builder.Build().RunAsync() already handles SIGINT/SIGTERM. If you have background work to flush, use IHostApplicationLifetime:

var host = builder.Build();
var lifetime = host.Services.GetRequiredService<IHostApplicationLifetime>();
lifetime.ApplicationStopping.Register(() =>
{
    // flush, close handles, etc. — keep it fast (<5s) so the client doesn't hang.
});
await host.RunAsync();