Dotnet Mcp Builder

Building MCP servers in .NET

This skill helps you write production-quality MCP servers and basic clients in C#/.NET against the official `ModelContextProtocol` NuGet packages, maintained by Microsoft and the MCP project. It targets the stable 1.x line and the current spec (2025-11-25).

When this skill earns its keep

The .NET MCP SDK had years of preview packages (0.x-preview) before reaching 1.0. Without help, the model tends to:

• Pin a stale preview version that won't compile against current samples.
• Miss recent spec features (elicitation URL mode, MCP Apps, structured content blocks).
• Get HTTP transport details wrong (stateful/stateless, proxy buffering, OAuth wiring).
• Forget the STDIO stdout/stderr trap.

If the task is one of those, load the matching reference and follow it. If it's truly trivial (e.g. "rename this tool method"), you don't need to read everything — the cardinal rules below are the minimum.

Mental model in 30 seconds

A .NET MCP server is an ordinary Microsoft.Extensions.Hosting (or WebApplication) app that wires an MCP server through DI:

builder.Services
    .AddMcpServer()
    .WithStdioServerTransport()      // OR .WithHttpTransport(...)
    .WithToolsFromAssembly()         // discover [McpServerToolType] classes
    .WithPrompts<MyPrompts>()        // optional
    .WithResources<MyResources>();   // optional

Primitives are plain C# methods on classes marked with attributes ([McpServerToolType] + [McpServerTool], [McpServerPromptType] + [McpServerPrompt], [McpServerResourceType] + [McpServerResource]). Parameters bind from JSON-RPC; the SDK builds the JSON Schema from the signature plus [Description] attributes.

Server-to-client features (sampling, elicitation, roots, log/progress notifications) are methods on the injected IMcpServer.

Decision tree → which references to load

Always load references/packages.md if you're creating a new project or unsure of the current package version.

For multi-primitive tasks, load several at once. For trivial edits in an existing file, you usually don't need any.

Cardinal rules (apply always; these prevent the highest-frequency breakages)

1. Pin the current stable package, not a preview. Use ModelContextProtocol / ModelContextProtocol.AspNetCore / ModelContextProtocol.Core at the latest 1.x. If you find yourself writing 0.3-preview or 0.4-preview, stop and check NuGet — preview APIs have breaking differences. 2. STDIO servers must not write to stdout. Stdout is the JSON-RPC channel. Configure LogToStandardErrorThreshold = LogLevel.Trace before anything else and never Console.WriteLine from a tool. 3. HTTP defaults to stateful. For horizontally-scaled deployments without server-initiated traffic, set options.Stateless = true. Server-to-client features (sampling, elicitation, roots, unsolicited notifications) require stateful HTTP or STDIO — Stateless = true will break them at runtime. 4. SSE-only is deprecated. Use Streamable HTTP. Only enable legacy SSE (EnableLegacySse = true) for an old client you must support, and call it out. 5. Always `[Description]` tools and parameters. This is what the LLM sees when picking and shaping calls. Vague descriptions are the #1 reason tools don't get used. 6. Show the registration line every time you add a primitive. A new [McpServerPromptType] class without .WithPrompts<...>() (or .WithPromptsFromAssembly()) is invisible. 7. Don't invent APIs. If you're unsure a method exists, say so and check the API reference — wrong method names cause silent failures.

Working style

• Make minimal, additive changes. Add a method to the existing tool class rather than restructuring the project.
• For non-trivial setups, run `dotnet build`. Catches missing usings, attribute typos, and TFM mismatches before the user sees them.
• Confirm transport + .NET version + primitives before scaffolding if context doesn't already make them obvious. Default to .NET 10 for new projects.

When the user is stuck

Walk this checklist before guessing: 1. STDIO: something is writing to stdout (logger sink, Console.WriteLine, library banner). 2. HTTP 404: path mismatch — app.MapMcp() is root, app.MapMcp("/mcp") puts it under /mcp. 3. Tool not appearing: missing [McpServerToolType] on the class, or no .WithToolsFromAssembly() / .WithTools<T>() registered. 4. Args not bound: parameter names must match the JSON-RPC arguments keys; complex types bind via System.Text.Json. 5. Sampling/elicitation/roots failing: transport is stateless HTTP, or the client doesn't advertise the capability.

Still stuck? Point the user at the `EverythingServer` sample — it exercises every feature.

Building an MCP client in .NET

A short reference for consuming an MCP server from .NET — useful for testing your server, building agent harnesses, or wiring MCP into a Semantic Kernel / Microsoft.Extensions.AI pipeline.

For just running a server, ignore this file.

Packages

dotnet add package ModelContextProtocol.Core   # minimal: just client + transports
# or
dotnet add package ModelContextProtocol         # adds DI/hosting helpers

Connecting via STDIO (launching a server process)

using ModelContextProtocol.Client;

var transport = new StdioClientTransport(new StdioClientTransportOptions
{
    Command = "dotnet",
    Arguments = ["run", "--project", "../MyMcpServer"],
    EnvironmentVariables = new() { ["MY_API_KEY"] = "..." },
    ShutdownTimeout = TimeSpan.FromSeconds(10),
    StandardErrorLines = line => Console.Error.WriteLine($"[server] {line}")
});

await using var client = await McpClient.CreateAsync(transport);

StandardErrorLines is a great debugging aid — you'll see your server's logs as they happen.

Connecting via HTTP (Streamable)

using ModelContextProtocol.Client;

var transport = new HttpClientTransport(new HttpClientTransportOptions
{
    Endpoint = new Uri("https://my-server.example.com/mcp"),
    TransportMode = HttpTransportMode.StreamableHttp,
    ConnectionTimeout = TimeSpan.FromSeconds(30),
    AdditionalHeaders = new Dictionary<string, string>
    {
        ["Authorization"] = "Bearer ..."
    }
});

await using var client = await McpClient.CreateAsync(transport);

TransportMode = AutoDetect (the default) tries Streamable HTTP first and falls back to SSE — useful for older servers, but pin to StreamableHttp for new code so failures are loud.

Listing and calling tools

IList<McpClientTool> tools = await client.ListToolsAsync();

foreach (var t in tools)
    Console.WriteLine($"- {t.Name}: {t.Description}");

var echo = tools.First(t => t.Name == "Echo");
CallToolResult result = await echo.CallAsync(new Dictionary<string, object?>
{
    ["message"] = "hello"
});

if (result.IsError == true)
{
    var msg = result.Content.OfType<TextContentBlock>().FirstOrDefault()?.Text;
    Console.Error.WriteLine($"Tool failed: {msg}");
    return;
}

foreach (var block in result.Content)
{
    switch (block)
    {
        case TextContentBlock text:
            Console.WriteLine(text.Text);
            break;
        case ImageContentBlock image:
            File.WriteAllBytes("out.png", image.DecodedData.ToArray());
            break;
    }
}

Listing prompts and resources

IList<McpClientPrompt> prompts = await client.ListPromptsAsync();
GetPromptResult pr = await client.GetPromptAsync("code_review",
    new Dictionary<string, object?> { ["language"] = "csharp", ["code"] = "..." });

IList<McpClientResource> resources = await client.ListResourcesAsync();
ReadResourceResult rr = await client.ReadResourceAsync("config://app/settings");

Subscribing to server notifications

client.RegisterNotificationHandler(
    NotificationMethods.ToolListChangedNotification,
    async (notification, ct) =>
    {
        var updated = await client.ListToolsAsync(cancellationToken: ct);
        Console.WriteLine($"Tool list changed; now {updated.Count} tools.");
    });

Handling server-to-client requests (sampling, elicitation, roots)

If your server uses these features, your client must handle them. Configure handlers when creating the client:

await using var client = await McpClient.CreateAsync(transport, new McpClientOptions
{
    Capabilities = new()
    {
        Sampling = new()
        {
            SamplingHandler = async (req, progress, ct) =>
            {
                // Route req.Messages to your IChatClient and return a CreateMessageResult.
                var response = await myChatClient.GetResponseAsync(/* convert */, ct);
                return new CreateMessageResult { /* fill in */ };
            }
        },
        Elicitation = new()
        {
            ElicitationHandler = async (req, ct) =>
            {
                // Show req.Message + req.RequestedSchema to the user; collect input.
                return new ElicitResult { Action = "accept", Content = collectedValues };
            }
        },
        Roots = new()
        {
            RootsHandler = async (req, ct) =>
            {
                return new ListRootsResult
                {
                    Roots = new[] { new Root { Uri = "file:///workspace", Name = "Workspace" } }
                };
            }
        }
    }
});

If you don't supply a handler and the server calls the feature, the call fails with a "method not supported" error.

Using MCP tools as IChatClient function tools

If you're plugging MCP into a Microsoft.Extensions.AI pipeline, expose tools as AIFunction:

using Microsoft.Extensions.AI;

IList<McpClientTool> mcpTools = await client.ListToolsAsync();

var chatOptions = new ChatOptions
{
    Tools = mcpTools.Cast<AITool>().ToList()
};

var chatClient = new MyChatClient(...);   // any IChatClient
var response = await chatClient.GetResponseAsync(messages, chatOptions);

McpClientTool implements AIFunction — function-calling middleware will invoke the right tool and feed the result back to the LLM automatically.

Resuming a session (HTTP, stateful)

var transport = new HttpClientTransport(new HttpClientTransportOptions
{
    Endpoint = new Uri("https://my-server.example.com/mcp"),
    KnownSessionId = previousSessionId
});

await using var client = await McpClient.ResumeSessionAsync(transport, new ResumeClientSessionOptions
{
    ServerCapabilities = previousServerCapabilities,
    ServerInfo = previousServerInfo
});

Useful for long-lived agent processes that survive transient network drops.

Elicitation

Elicitation lets a tool ask the user for input mid-execution, via the client. The LLM doesn't see the question; the client surfaces it directly to the user. This turns one-shot tool calls into interactive flows — collecting confirmation, missing parameters, credentials (URL mode), etc.

Spec version: 2025-11-25. URL mode is the newer addition (originally 2025-06-18 had only form mode).

Two modes

Prerequisite: stateful transport

Elicitation requires the server to send a request to the client and wait for a response. That only works on:

• STDIO (always).
• Stateful HTTP (options.Stateless = false).

In stateless HTTP, ElicitAsync will throw — there's no transport channel back.

Form mode — full example

using System.ComponentModel;
using ModelContextProtocol.Protocol;
using ModelContextProtocol.Server;

[McpServerToolType]
public class BookingTools
{
    [McpServerTool, Description("Books a meeting room. Asks the user for confirmation.")]
    public static async Task<string> BookRoom(
        IMcpServer server,
        [Description("Room name")] string room,
        [Description("Start time (ISO 8601)")] DateTime start,
        CancellationToken ct)
    {
        var elicit = await server.ElicitAsync(new ElicitRequestParams
        {
            Message = $"Confirm booking '{room}' at {start:HH:mm}?",
            RequestedSchema = new ElicitRequestParams.RequestSchema
            {
                Properties = new Dictionary<string, ElicitRequestParams.PrimitiveSchemaDefinition>
                {
                    ["confirm"] = new ElicitRequestParams.BooleanSchema
                    {
                        Description = "Confirm the booking",
                        Default = true
                    },
                    ["notes"] = new ElicitRequestParams.StringSchema
                    {
                        Description = "Optional notes for the booking"
                    }
                }
            }
        }, ct);

        if (elicit.Action != "accept")
            return "Booking cancelled by user.";

        var confirmed = elicit.Content?["confirm"].GetBoolean() ?? false;
        var notes     = elicit.Content?["notes"].GetString() ?? "";

        if (!confirmed)
            return "User declined to confirm.";

        // …perform the booking…
        return $"Booked '{room}' at {start:O}. Notes: {notes}";
    }
}

Schema primitive types

You can build a RequestedSchema from these:

Each accepts Description and Default.

Response shape

ElicitResult:

• Action — "accept", "reject", or "cancel". Always check this first.
• Content — Dictionary<string, JsonElement>? with the user's submitted values. null if the user rejected/cancelled.

Always handle the non-accept paths:

if (elicit.Action == "cancel")
    return "User cancelled. No changes made.";
if (elicit.Action == "reject")
    return "User declined.";
// Action == "accept" → safe to read elicit.Content

URL mode — full example

URL mode is for flows where the user must complete something outside the MCP channel — typically OAuth.

[McpServerTool, Description("Connects the user's GitHub account.")]
public static async Task<string> ConnectGitHub(
    IMcpServer server,
    IOAuthService oauth,
    CancellationToken ct)
{
    var elicitationId = Guid.NewGuid().ToString();
    var authUrl = oauth.BuildAuthorizationUrl(state: elicitationId);

    var result = await server.ElicitAsync(new ElicitRequestParams
    {
        Mode = "url",
        ElicitationId = elicitationId,
        Url = authUrl,
        Message = "Please authorize access to GitHub in the browser window that just opened."
    }, ct);

    if (result.Action != "accept")
        return "Authorization cancelled.";

    // The user has come back. Look up the persisted token by elicitationId.
    var token = await oauth.GetTokenByStateAsync(elicitationId, ct);
    return token is not null ? "Connected." : "Authorization did not complete.";
}

UrlElicitationRequiredException

When a tool is blocked on auth (rather than walking the user through it), throw UrlElicitationRequiredException. The client surfaces the URL to the user and the call fails cleanly. Useful for retry-after-auth patterns:

if (!oauth.HasValidToken)
{
    var id = Guid.NewGuid().ToString();
    throw new UrlElicitationRequiredException(
        "Authorization required",
        new[]
        {
            new ElicitRequestParams
            {
                Mode = "url",
                ElicitationId = id,
                Url = oauth.BuildAuthorizationUrl(state: id),
                Message = "Sign in to continue."
            }
        });
}

When NOT to use elicitation

• Trivial confirmations the LLM can ask in natural language. If you can phrase "Should I do X?" in your tool's docstring and let the LLM ask, that's lower friction than a modal form.
• Branching that the LLM should reason about. Don't replace the LLM's judgment with a form — only elicit for things the LLM literally cannot decide (user secrets, real-time consent, picking from a list only the user knows).
• Stateless deployments. Doesn't work — see prerequisite above.

Client capability check

Don't blindly call ElicitAsync. Check first:

if (server.ClientCapabilities?.Elicitation is null)
    return "This client doesn't support elicitation; please pass the value as an argument.";

var elicit = await server.ElicitAsync(...);

This degrades gracefully on older clients.

MCP Apps (interactive UI)

MCP Apps is the official extension that lets a tool return an interactive UI rendered in a sandboxed iframe inside the host (Claude, Claude Desktop, VS Code Copilot, Goose, Postman, MCPJam). Typical use cases: charts, dashboards, multi-step forms, 3D viewers, real-time monitors, PDF/video viewers.

Important: as of early 2026, the C# SDK does not ship a typed convenience layer for MCP Apps (tracked in csharp-sdk#1431). You implement the spec by hand: serve a ui:// resource and emit the right _meta on the tool. It's not hard — just untyped. This page shows you the pattern.

How it works (short version)

1. You register a resource at a ui:// URI returning an HTML bundle. 2. You register a tool whose definition includes _meta.ui.resourceUri pointing to that URI. 3. When the LLM calls the tool, the host fetches the UI resource and renders it in a sandboxed iframe in the chat. 4. The HTML talks to the host over postMessage JSON-RPC (use @modelcontextprotocol/ext-apps from the bundle, or hand-roll it). 5. The app can call back into your MCP server (any tool), update the model context, etc.

The full protocol spec is at `@modelcontextprotocol/ext-apps`.

Step 1: Serve the UI resource

Bundle your HTML/JS/CSS into a single string (or load from wwwroot). Serve it at a ui:// URI.

using System.ComponentModel;
using System.IO;
using System.Reflection;
using ModelContextProtocol.Protocol;
using ModelContextProtocol.Server;

[McpServerResourceType]
public static class ChartUiResource
{
    [McpServerResource(
        UriTemplate = "ui://charts/interactive",
        Name = "Interactive chart",
        MimeType = "text/html+skybridge")]   // see "MIME type" note below
    [Description("UI bundle for the interactive chart MCP App.")]
    public static TextResourceContents GetUi()
    {
        // Load a bundled HTML/JS file from embedded resources or wwwroot.
        var html = LoadEmbeddedString("MyMcpServer.AppUi.chart.html");

        return new TextResourceContents
        {
            Uri = "ui://charts/interactive",
            MimeType = "text/html+skybridge",
            Text = html
        };
    }

    private static string LoadEmbeddedString(string resourceName)
    {
        var asm = Assembly.GetExecutingAssembly();
        using var stream = asm.GetManifestResourceStream(resourceName)
            ?? throw new InvalidOperationException($"Missing embedded resource {resourceName}");
        using var reader = new StreamReader(stream);
        return reader.ReadToEnd();
    }
}

MIME type note: the spec uses text/html+skybridge for app HTML so hosts can distinguish UI bundles from regular text/html previews. Use that, even though plain text/html may work today on lenient hosts.

Step 2: Emit _meta on the tool

The C# SDK's [McpServerTool] doesn't expose _meta in the attribute today, so set it via the lower-level Tool definition. Do this once at startup:

using ModelContextProtocol.Protocol;
using ModelContextProtocol.Server;
using System.Text.Json;
using System.Text.Json.Nodes;

builder.Services.Configure<McpServerOptions>(options =>
{
    options.Capabilities ??= new();
    options.Capabilities.Tools ??= new();

    // Define the tool manually so we can attach _meta.
    var visualizeTool = new Tool
    {
        Name = "visualize_data",
        Description = "Visualize the user's data as an interactive chart.",
        InputSchema = JsonDocument.Parse("""
            {
              "type": "object",
              "properties": {
                "datasetId": { "type": "string", "description": "Dataset to visualize." }
              },
              "required": ["datasetId"]
            }
            """).RootElement,
        Meta = new JsonObject
        {
            ["ui"] = new JsonObject
            {
                ["resourceUri"] = "ui://charts/interactive"
                // Optionally:
                // ["csp"] = new JsonObject { ["default-src"] = "'self' https://cdn.example.com" },
                // ["permissions"] = new JsonArray("clipboard-write")
            }
        }
    };

    // Implement the call handler that returns the data the UI will render.
    options.Capabilities.Tools.ToolCollection ??= new();
    options.Capabilities.Tools.ToolCollection.Add(McpServerTool.Create(
        async (CallToolRequestParams req, CancellationToken ct) =>
        {
            var args = req.Arguments ?? new();
            var datasetId = args["datasetId"]!.GetValue<string>();
            var data = await LoadDataset(datasetId, ct);
            return new CallToolResult
            {
                Content = [new TextContentBlock { Text = JsonSerializer.Serialize(data) }],
                StructuredContent = JsonSerializer.SerializeToNode(data)
            };
        },
        visualizeTool));
});

If you don't need full structured content, the tool can return just JSON in a text block — the UI fetches it via app.callServerTool(...) after rendering.

Backwards compatibility key

Some older hosts expect _meta["ui/resourceUri"] instead of _meta.ui.resourceUri. Set both for safety:

Meta = new JsonObject
{
    ["ui"] = new JsonObject { ["resourceUri"] = "ui://charts/interactive" },
    ["ui/resourceUri"] = "ui://charts/interactive"   // legacy
}

Step 3: The HTML bundle

A minimum viable bundle: vanilla JS using @modelcontextprotocol/ext-apps. The simplest build is a single self-contained HTML file.

<!doctype html>
<html>
  <head>
    <meta charset="utf-8" />
    <title>Chart</title>
    <style>body { font-family: system-ui; margin: 0; }</style>
  </head>
  <body>
    <div id="root">Loading…</div>
    <script type="module">
      import { App } from "https://esm.sh/@modelcontextprotocol/ext-apps@1";

      const app = new App();
      await app.connect();

      // Fetch the data we need from the server.
      const resp = await app.callServerTool({
        name: "visualize_data",
        arguments: { datasetId: "default" }
      });

      const data = JSON.parse(resp.content[0].text);
      document.getElementById("root").textContent =
        `Loaded ${data.points.length} data points.`;

      // Tell the model what just happened (becomes part of its context).
      await app.updateModelContext({
        content: [{ type: "text", text: "User opened the chart UI." }]
      });
    </script>
  </body>
</html>

Tip: for non-trivial UIs, build with Vite (React/Vue/Svelte/Solid — any of the official starter templates) and have the build emit a single inlined HTML you embed as a project resource.

Project layout

A pragmatic layout for an MCP App in .NET:

MyMcpServer/
├── Program.cs
├── Tools/
│   └── VisualizeDataTool.cs       # (or registered via Configure as above)
├── Resources/
│   └── ChartUiResource.cs         # serves the ui:// resource
├── AppUi/
│   ├── chart.html                 # bundled UI (Embedded Resource)
│   └── package.json + src/...     # if you build with Vite, output to chart.html
└── MyMcpServer.csproj

In the csproj:

<ItemGroup>
  <EmbeddedResource Include="AppUi\chart.html" />
</ItemGroup>

Read it via Assembly.GetManifestResourceStream("MyMcpServer.AppUi.chart.html").

Testing locally

1. Run your MCP server (STDIO or HTTP). 2. Use a host that supports MCP Apps — Claude Desktop or VS Code Copilot Chat are the easiest. 3. Trigger the tool via the LLM. The UI renders inline.

For pure-UI iteration, MCP Inspector shows resource contents but does not fully render apps; for that, point Claude Desktop at your dev server.

Pitfalls

• Wrong MIME type. Use text/html+skybridge. Plain text/html may still work but isn't future-proof.
• CSP too tight or too loose. If your UI loads from a CDN, declare it in Meta["ui"]["csp"] on the Tool definition (this serialises to _meta.ui.csp on the wire). Otherwise the iframe sandbox blocks it.
• Forgetting `Tool.Meta` on the tool. Without the Meta property containing the ui.resourceUri entry, the host treats your tool as a regular text-returning tool. The UI never appears.
• Trying to use browser APIs outside the sandbox. No cookies, no localStorage from the parent. Use app.updateModelContext and tool calls for state.

Future-proofing

When the C# SDK ships its typed MCP Apps helpers (issue #1431), you'll likely be able to replace the manual Configure block with an attribute or fluent builder. The serving of ui:// resources won't change. Keep your UI HTML as embedded resources so the migration is mechanical.

NuGet packages and target frameworks

The three official packages

All packages live under the `ModelContextProtocol` NuGet profile. The official C# SDK repo is `modelcontextprotocol/csharp-sdk`, maintained jointly by the MCP project and Microsoft.

Rule of thumb:

• New STDIO server → ModelContextProtocol + Microsoft.Extensions.Hosting.
• New HTTP server → ModelContextProtocol.AspNetCore only (it transitively pulls in everything you need).
• Pure client app → ModelContextProtocol.Core (or ModelContextProtocol if you also want hosting/DI for the client).

Versions

As of 2026, the stable line is 1.x (1.2.0 is current at time of writing). The 0.x line was preview and has breaking differences — if you find docs or blog posts referencing 0.4/0.6, treat them as out of date.

To check the latest:

dotnet search ModelContextProtocol --prerelease

Target frameworks

The SDK targets `.NET 8.0` and `netstandard2.0`. That means it runs on:

• .NET 8 (LTS)
• .NET 9
• .NET 10 (current LTS — recommended for new projects)
• .NET Framework 4.6.2+ via netstandard2.0 (rare; only for legacy hosts)

For HTTP servers you specifically need a TFM that supports ASP.NET Core (so .NET 8/9/10).

Project setup commands

STDIO server

dotnet new console -n MyMcpServer -f net10.0
cd MyMcpServer
dotnet add package ModelContextProtocol
dotnet add package Microsoft.Extensions.Hosting

HTTP (Streamable) server

dotnet new web -n MyMcpServer -f net10.0
cd MyMcpServer
dotnet add package ModelContextProtocol.AspNetCore

(dotnet new web gives you a minimal ASP.NET Core project — exactly what MapMcp needs.)

Client

dotnet new console -n MyMcpClient -f net10.0
cd MyMcpClient
dotnet add package ModelContextProtocol.Core

Optional but commonly useful

What about dnx?

Newer Microsoft examples sometimes show launching servers via dnx PackageName --version 1.2.3. That's a valid distribution model: publish your server as a NuGet package and let users run it without cloning. It's orthogonal to how the server itself is built — keep your code identical and just change the launch command.

Prompts

Prompts are reusable, parameterised message templates that the user (not the LLM) typically picks from a list — think "slash commands" in a chat client. The server defines them; the host renders them as menus.

Anatomy of a prompt

using System.ComponentModel;
using Microsoft.Extensions.AI;
using ModelContextProtocol.Server;

[McpServerPromptType]
public class CodePrompts
{
    [McpServerPrompt, Description("Generates a code review prompt.")]
    public static IEnumerable<ChatMessage> CodeReview(
        [Description("The programming language")] string language,
        [Description("The code to review")] string code) =>
        [
            new(ChatRole.User,
                $"Please review the following {language} code:\n\n```{language}\n{code}\n```"),
            new(ChatRole.Assistant,
                "I'll review the code for correctness, style, and potential improvements.")
        ];
}

Register it:

.WithPrompts<CodePrompts>()
// or
.WithPromptsFromAssembly()

Return types

ChatMessage/ChatRole come from Microsoft.Extensions.AI. They're the high-level shape and what you should use 90% of the time. Drop down to PromptMessage/ContentBlock only when you need embedded resources or fine-grained content typing.

Arguments

Every parameter (after the special ones the SDK strips out — IMcpServer, CancellationToken, etc.) becomes a prompt argument visible to the user when they pick the prompt. Use [Description] on each to explain what the user should supply.

To mark an argument optional, give it a default value:

[McpServerPrompt, Description("…")]
public static ChatMessage Greeting(
    [Description("Their preferred greeting style")] string style = "casual")
    => new(ChatRole.User, $"Greet me in a {style} style.");

Image and file content

For prompts that include images:

[McpServerPrompt, Description("Asks the model to analyze an image.")]
public static IEnumerable<ChatMessage> AnalyzeImage(
    [Description("Instructions for the analysis")] string instructions)
{
    byte[] imageBytes = LoadSampleImage();
    return new[]
    {
        new ChatMessage(ChatRole.User, new AIContent[]
        {
            new TextContent($"Please analyze this image: {instructions}"),
            new DataContent(imageBytes, "image/png")
        })
    };
}

For embedded text resources (e.g. seeding the conversation with a document the user picked):

[McpServerPrompt, Description("Reviews a referenced document.")]
public static IEnumerable<PromptMessage> ReviewDocument(
    [Description("The document ID to review")] string documentId)
{
    string content = LoadDocument(documentId);
    return new[]
    {
        new PromptMessage
        {
            Role = Role.User,
            Content = new TextContentBlock { Text = "Please review the following document:" }
        },
        new PromptMessage
        {
            Role = Role.User,
            Content = new EmbeddedResourceBlock
            {
                Resource = new TextResourceContents
                {
                    Uri = $"docs://documents/{documentId}",
                    MimeType = "text/plain",
                    Text = content
                }
            }
        }
    };
}

Async prompts

Prompts can be async — useful when you need to look up data to build the messages:

[McpServerPrompt, Description("Drafts a release-notes prompt.")]
public static async Task<IEnumerable<ChatMessage>> ReleaseNotes(
    string repo,
    string fromTag,
    string toTag,
    IGitHubClient github,
    CancellationToken ct)
{
    var commits = await github.GetCommitsBetweenAsync(repo, fromTag, toTag, ct);
    var summary = string.Join("\n", commits.Select(c => $"- {c.Message}"));
    return new[]
    {
        new ChatMessage(ChatRole.User,
            $"Draft release notes for {repo} {fromTag}→{toTag} from these commits:\n{summary}")
    };
}

Notifying clients of prompt changes

await server.SendNotificationAsync(
    NotificationMethods.PromptListChangedNotification,
    new PromptListChangedNotificationParams(),
    cancellationToken);

When to use prompts vs. tools

• Prompt: the user triggers it from a menu, supplying any required arguments. The output is messages, not data. Good for "/summarize", "/code-review", "/draft-email".
• Tool: the LLM triggers it (often without explicit user action) to fetch or change data. Good for "get_weather", "create_issue".

If both apply (the user wants a slash command that triggers the same logic the LLM could call), expose both — the same DTO/service can back both.

Resources

Resources are server-exposed "things" identified by a URI. Hosts list them so the user can pick which ones to attach to the conversation; tools and prompts can also reference them via EmbeddedResourceBlock. Think files, database rows, API objects, settings — anything addressable.

Two flavours:

• Static resource — a fixed URI (config://app/settings). Useful for singletons.
• Resource template — a URI with placeholders (docs://articles/{id}). The host (or LLM) substitutes parameters; your method receives them.

Static resource

using System.ComponentModel;
using System.Text.Json;
using ModelContextProtocol.Server;

[McpServerResourceType]
public class AppResources
{
    [McpServerResource(
        UriTemplate = "config://app/settings",
        Name = "App Settings",
        MimeType = "application/json")]
    [Description("Returns application configuration settings.")]
    public static string GetSettings() =>
        JsonSerializer.Serialize(new { theme = "dark", language = "en" });
}

Register:

.WithResources<AppResources>()
// or
.WithResourcesFromAssembly()

Templated resource

The placeholders in UriTemplate map by name to method parameters. Anything not a placeholder follows the same DI rules as tools (IMcpServer, CancellationToken, services).

[McpServerResourceType]
public class DocumentResources
{
    [McpServerResource(
        UriTemplate = "docs://articles/{id}",
        Name = "Article",
        MimeType = "text/markdown")]
    [Description("Returns an article by its ID.")]
    public static ResourceContents GetArticle(string id)
    {
        string? content = LoadArticle(id);
        if (content is null)
            throw new McpException($"Article not found: {id}");

        return new TextResourceContents
        {
            Uri = $"docs://articles/{id}",
            MimeType = "text/markdown",
            Text = content
        };
    }
}

Return types

Binary resource

[McpServerResource(
    UriTemplate = "images://photos/{id}",
    Name = "Photo",
    MimeType = "image/png")]
public static BlobResourceContents GetPhoto(int id)
{
    byte[] data = LoadPhoto(id);
    return BlobResourceContents.FromBytes(data, $"images://photos/{id}", "image/png");
}

Pointing at the file system

A common pattern is exposing files from disk. Be careful about path traversal — never trust the URI verbatim.

[McpServerResource(
    UriTemplate = "file://workspace/{*relativePath}",
    Name = "Workspace file")]
public static TextResourceContents ReadFile(string relativePath, IOptions<WorkspaceOptions> opts)
{
    var root = opts.Value.RootPath;
    var fullPath = Path.GetFullPath(Path.Combine(root, relativePath));
    if (!fullPath.StartsWith(root, StringComparison.Ordinal))
        throw new McpException("Path traversal blocked.");

    return new TextResourceContents
    {
        Uri = $"file://workspace/{relativePath.Replace("\\", "/")}",
        MimeType = "text/plain",
        Text = File.ReadAllText(fullPath)
    };
}

Listing dynamic resources

Attribute-based discovery covers the common case (one method per template). When you need to enumerate resources that don't fit a template — say, "list every file in the workspace" — implement a low-level handler in McpServerOptions.Capabilities.Resources:

builder.Services.Configure<McpServerOptions>(options =>
{
    options.Capabilities ??= new();
    options.Capabilities.Resources ??= new();

    options.Capabilities.Resources.ListResourcesHandler = (ctx, ct) =>
    {
        var resources = Directory
            .EnumerateFiles(WorkspaceRoot, "*.*", SearchOption.AllDirectories)
            .Select(path => new Resource
            {
                Uri = "file://workspace/" + Path.GetRelativePath(WorkspaceRoot, path).Replace('\\', '/'),
                Name = Path.GetFileName(path),
                MimeType = "text/plain"
            })
            .ToList();

        return ValueTask.FromResult(new ListResourcesResult { Resources = resources });
    };
});

You can mix attribute-based and handler-based — the SDK merges both.

Resource subscriptions (server-pushed updates)

If a client subscribes to a resource and it changes, push a notification:

await server.SendNotificationAsync(
    NotificationMethods.ResourceUpdatedNotification,
    new ResourceUpdatedNotificationParams { Uri = "docs://articles/42" },
    cancellationToken);

For wholesale list changes:

await server.SendNotificationAsync(
    NotificationMethods.ResourceListChangedNotification,
    new ResourceListChangedNotificationParams(),
    cancellationToken);

Both require a stateful transport.

Reading resources from a client

ReadResourceResult result = await client.ReadResourceAsync("config://app/settings");
foreach (var content in result.Contents)
{
    if (content is TextResourceContents text)
        Console.WriteLine($"[{text.MimeType}] {text.Text}");
    else if (content is BlobResourceContents blob)
        File.WriteAllBytes("out.bin", blob.DecodedData.ToArray());
}

Resources vs. tools — when to pick which

• Resource: the user (or LLM) wants to attach context to the conversation. Read-only, addressable, listable. The host controls when/whether to load it. Ideal for documents, configs, schemas.
• Tool: the LLM wants to do something (which may include reading data). Side-effects, actions, parameters that don't fit a URI.

If you have something the LLM might want to search over, expose both: a search_articles tool and docs://articles/{id} resource template. The tool returns a list of URIs; the host fetches the content via the resource.

Roots

Roots are filesystem (or URI) locations the client advertises to the server, scoping what the server is allowed to look at. Think "open workspace folders" in an IDE — the user has implicitly approved the server reading from these places. The server pulls the list when it needs it.

When you'd use roots

• Building a tool that scans/edits the user's project. Use roots to know which directories are in scope.
• Resolving relative paths in a way that respects the user's open workspace.
• Restricting file access to the advertised roots (defence in depth).

Prerequisite

Same as sampling/elicitation: server-to-client request → needs STDIO or stateful HTTP. Plus the client must advertise the roots capability.

Reading roots from a tool

using System.ComponentModel;
using System.Text;
using ModelContextProtocol.Protocol;
using ModelContextProtocol.Server;

[McpServerToolType]
public class WorkspaceTools
{
    [McpServerTool, Description("Lists the user's project roots.")]
    public static async Task<string> ListProjectRoots(
        IMcpServer server,
        CancellationToken cancellationToken)
    {
        if (server.ClientCapabilities?.Roots is null)
            return "Client does not support roots.";

        var result = await server.RequestRootsAsync(
            new ListRootsRequestParams(),
            cancellationToken);

        var sb = new StringBuilder();
        foreach (var root in result.Roots)
            sb.AppendLine($"- {root.Name ?? root.Uri}: {root.Uri}");

        return sb.ToString();
    }
}

Root has Uri (string, often a file://...) and optional Name (display label).

Reacting to root changes

Clients send notifications/roots/list_changed when the user opens or closes a workspace folder. Subscribe:

builder.Services.Configure<McpServerOptions>(options =>
{
    options.Capabilities ??= new();

    // The client tells us its roots changed; refresh whatever cache we have.
    options.Capabilities.NotificationHandlers ??= [];
    options.Capabilities.NotificationHandlers[NotificationMethods.RootsListChangedNotification] =
        async (notification, ct) =>
        {
            // Trigger your refresh — typically pull RequestRootsAsync again.
        };
});

A useful pattern: cache + refresh

Roots don't change often, but refetching on every tool call is wasteful. Cache them per session and refresh on roots/list_changed:

public class RootsCache
{
    private IReadOnlyList<Root> _roots = Array.Empty<Root>();

    public IReadOnlyList<Root> Current => _roots;

    public async Task RefreshAsync(IMcpServer server, CancellationToken ct)
    {
        if (server.ClientCapabilities?.Roots is null) return;
        var result = await server.RequestRootsAsync(new ListRootsRequestParams(), ct);
        _roots = result.Roots;
    }
}

Register as singleton (per-session in stateful HTTP, naturally singleton in STDIO).

Validating paths against roots

Defence in depth: even if a tool argument looks like a path under a root, validate.

public static bool IsUnderAnyRoot(string absolutePath, IReadOnlyList<Root> roots)
{
    foreach (var root in roots)
    {
        if (!Uri.TryCreate(root.Uri, UriKind.Absolute, out var uri)) continue;
        if (!uri.IsFile) continue;
        var rootPath = Path.GetFullPath(uri.LocalPath);
        if (absolutePath.StartsWith(rootPath, StringComparison.OrdinalIgnoreCase))
            return true;
    }
    return false;
}

If a tool receives a path outside the advertised roots, refuse with a clear message — don't silently expand scope.

Sampling

Sampling lets a tool call the LLM through the client instead of bringing its own model. The server says "summarise this for me" and the client routes the request to whatever model the user has configured (Claude, GPT, local model, anything). Costs and rate limits live with the client, not the server.

When to use sampling

• The tool needs an LLM step (summarise, classify, draft, extract) and you don't want to ship/configure your own model in the server.
• You want to respect the user's model choice, key, and cost preferences.
• You're building a "meta" tool that orchestrates LLM work as part of its job (e.g. multi-step agents).

If you already have a deterministic algorithm, don't add a sampling call "for flavour" — it adds latency and cost.

Prerequisite: stateful transport

Like elicitation, sampling needs the server to call back to the client. STDIO works always; HTTP needs options.Stateless = false.

Recommended: IChatClient adapter

The cleanest API wraps the sampling channel as Microsoft.Extensions.AI.IChatClient, so you write code that looks like normal LLM-calling .NET:

using System.ComponentModel;
using Microsoft.Extensions.AI;
using ModelContextProtocol.Server;

[McpServerToolType]
public class SummaryTools
{
    [McpServerTool(Name = "SummarizeContent"), Description("Summarises arbitrary text using the client's LLM.")]
    public static async Task<string> Summarize(
        IMcpServer server,
        [Description("The text to summarize")] string text,
        CancellationToken cancellationToken)
    {
        ChatMessage[] messages =
        [
            new(ChatRole.User, "Briefly summarize the following content:"),
            new(ChatRole.User, text),
        ];

        var options = new ChatOptions
        {
            MaxOutputTokens = 256,
            Temperature = 0.3f,
        };

        var response = await server.AsSamplingChatClient()
            .GetResponseAsync(messages, options, cancellationToken);

        return $"Summary: {response}";
    }
}

Why this is nice:

• Same IChatClient API the rest of the .NET AI ecosystem uses.
• Works with Microsoft.Extensions.AI middleware (rate limiting, retries, telemetry, function calling).
• You can swap to a direct provider in tests by injecting a different IChatClient.

Lower-level: SampleAsync

When you need full control over the request shape:

using ModelContextProtocol.Protocol;

CreateMessageResult result = await server.SampleAsync(
    new CreateMessageRequestParams
    {
        Messages =
        [
            new SamplingMessage
            {
                Role = Role.User,
                Content = [new TextContentBlock { Text = "What is 2 + 2?" }]
            }
        ],
        MaxTokens = 100,
        Temperature = 0.0f,
        SystemPrompt = "You are a precise calculator.",
        // ModelPreferences, StopSequences, IncludeContext...
    },
    cancellationToken);

string answer = result.Content
    .OfType<TextContentBlock>()
    .FirstOrDefault()?.Text ?? string.Empty;

ModelPreferences lets you hint at model selection (cost vs. speed vs. intelligence priority); the client decides the actual model.

ModelPreferences = new ModelPreferences
{
    Hints = [new ModelHint { Name = "claude" }],   // soft preference
    CostPriority = 0.2,        // 0..1
    SpeedPriority = 0.4,
    IntelligencePriority = 0.9,
}

IncludeContext

Sampling requests can ask the client to include context from the current conversation:

IncludeContext = ContextInclusion.ThisServer   // include this server's prior messages
// or AllServers, or None (default)

Useful when you need the LLM to consider what's happened in the chat so far without you re-supplying it.

Capability check

Always confirm the client supports sampling — many do not:

if (server.ClientCapabilities?.Sampling is null)
    throw new McpException(
        "This client does not support sampling. " +
        "Configure a model in the host or use a different MCP client.");

Performance notes

• Sampling calls are network round-trips (client → its provider → back). Expect 100ms–multiple seconds. Don't loop tightly.
• Token costs are paid by the user (their API key/quota). Be conservative with MaxTokens.
• Cancellation propagates: if the user kills the tool call, the sampling request is cancelled too.

Sampling vs. doing it server-side

For "smart" servers shipped to many users, prefer sampling. For internal corporate servers where you want consistent behaviour and you're already paying for the model, direct is fine.

Other server features (completions, logging, progress, filters)

A quick reference for the smaller MCP server features beyond the core primitives. Each section is short — load this file when one of these comes up.

Argument completions

Completions let the host autocomplete prompt arguments and resource template parameters. The user starts typing; the client asks the server "what are valid values?".

Implement via the low-level handler (no high-level attribute exists yet):

builder.Services.Configure<McpServerOptions>(options =>
{
    options.Capabilities ??= new();
    options.Capabilities.Completions ??= new();

    options.Capabilities.Completions.CompleteHandler = async (ctx, ct) =>
    {
        // ctx.Params.Ref tells us what they're completing (a prompt or resource).
        // ctx.Params.Argument has the partial value typed so far.
        var partial = ctx.Params.Argument.Value ?? "";
        var matches = MyDataSource
            .Where(x => x.StartsWith(partial, StringComparison.OrdinalIgnoreCase))
            .Take(100)
            .ToArray();

        return new CompleteResult
        {
            Completion = new()
            {
                Values = matches,
                HasMore = false,
                Total = matches.Length
            }
        };
    };
});

Useful for: project IDs, file names, enum values that depend on dynamic data.

Logging

Servers can emit log messages that hosts surface in their UI (and the LLM can sometimes see). Use the standard ILogger<T> injected via DI — the SDK plumbs it through.

public class WeatherTools
{
    private readonly ILogger<WeatherTools> _log;
    public WeatherTools(ILogger<WeatherTools> log) => _log = log;

    [McpServerTool, Description("…")]
    public string GetWeather(string city)
    {
        _log.LogInformation("Looking up weather for {City}", city);
        return "...";
    }
}

For STDIO servers, remember: console logging must go to stderr (LogToStandardErrorThreshold = LogLevel.Trace) — otherwise it corrupts the JSON-RPC stream. See `transport-stdio.md`.

To send a log specifically over the MCP channel (so the host UI sees it, not just your container logs):

await server.SendNotificationAsync(
    NotificationMethods.LoggingMessageNotification,
    new LoggingMessageNotificationParams
    {
        Level = LoggingLevel.Info,
        Logger = "weather",
        Data = JsonSerializer.SerializeToElement(new { city, latency_ms = 123 })
    },
    ct);

The client may have set a setLevel filter — don't spam levels below it.

Progress notifications

For long-running tools, send progress updates so the host can display a spinner with text:

[McpServerTool, Description("Processes a large dataset.")]
public static async Task<string> Process(
    IMcpServer server,
    RequestContext<CallToolRequestParams> ctx,
    string datasetId,
    CancellationToken ct)
{
    var progressToken = ctx.Params.Meta?.ProgressToken;

    for (int i = 0; i < 100; i++)
    {
        await Task.Delay(50, ct);

        if (progressToken is not null)
        {
            await server.SendNotificationAsync(
                NotificationMethods.ProgressNotification,
                new ProgressNotificationParams
                {
                    ProgressToken = progressToken,
                    Progress = i + 1,
                    Total = 100,
                    Message = $"Processing item {i + 1} of 100"
                },
                ct);
        }
    }

    return "Done.";
}

Only send progress if the client passed a progressToken in the request meta — otherwise the host isn't listening.

Notification handlers (server-side)

Servers can react to notifications the client sends:

options.Capabilities ??= new();
options.Capabilities.NotificationHandlers ??= [];

options.Capabilities.NotificationHandlers[NotificationMethods.RootsListChangedNotification] =
    async (notification, ct) =>
    {
        // Refresh root cache, etc.
    };

options.Capabilities.NotificationHandlers[NotificationMethods.CancelledNotification] =
    async (notification, ct) =>
    {
        // The client cancelled a request; if you have side-effects in flight, abort them.
    };

Filters / middleware

The SDK supports filters that wrap tool calls (think ASP.NET Core middleware for MCP). Use them for cross-cutting concerns: auth checks, telemetry, rate limiting, audit logging.

builder.Services
    .AddMcpServer()
    .WithStdioServerTransport()
    .WithToolsFromAssembly()
    .WithCallToolFilter(async (ctx, next) =>
    {
        var sw = Stopwatch.StartNew();
        try
        {
            return await next(ctx);
        }
        finally
        {
            sw.Stop();
            ctx.Server.Services?
                .GetRequiredService<ILogger<Program>>()
                .LogInformation("Tool {Tool} took {Ms}ms",
                    ctx.Params.Name, sw.ElapsedMilliseconds);
        }
    });

Similar With*Filter helpers exist for resources, prompts, and other capabilities — check the SDK API reference for the current set.

Server instructions (system-prompt-ish)

You can supply instructions sent to the client at initialise time. Hosts may include them in the LLM's system prompt.

builder.Services.AddMcpServer(options =>
{
    options.ServerInstructions =
        "Use the booking tools to schedule meetings. " +
        "Always confirm with the user before booking via elicitation.";
});

Keep this short — every token here costs the user.

Capabilities advertising

If you want to not advertise a capability you happen to have code for, you can mute it:

builder.Services.AddMcpServer(options =>
{
    options.Capabilities = new()
    {
        Tools = new(),       // advertise tools
        Prompts = new(),     // advertise prompts
        Resources = null,    // do NOT advertise resources, even if some are registered
        Logging = new()
    };
});

By default, the SDK advertises everything you've registered — usually the right behaviour.

Testing and local debugging

Three workflows: interactive testing with MCP Inspector, in-process integration tests, and CI-friendly unit tests.

MCP Inspector (interactive)

MCP Inspector is the go-to tool for trying out a server by hand. It launches your server, connects via STDIO or HTTP, and gives you a UI to list/call tools, view resources, fire elicitations, see logs, and inspect raw JSON-RPC frames.

STDIO

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

Pass env vars or args after --:

npx @modelcontextprotocol/inspector \
  dotnet run --project ./MyMcpServer -- \
  --some-flag value

HTTP

Start the server normally (dotnet run), then in Inspector pick "Streamable HTTP" and enter the URL (e.g. http://localhost:3001).

Use it for

• Verifying tool descriptions are clear (Inspector renders them like the LLM would consume them).
• Walking through elicitation flows without a real LLM.
• Capturing the exact JSON-RPC payloads when filing bug reports.

In-process integration tests (recommended)

The cleanest test setup uses InMemoryTransport (or the lower-level StreamServerTransport / StreamClientTransport) to wire a real server and a real client together in the same process. No subprocesses, no network.

using System.IO.Pipelines;
using ModelContextProtocol;
using ModelContextProtocol.Client;
using ModelContextProtocol.Protocol;
using ModelContextProtocol.Server;
using Xunit;

public class WeatherToolsTests
{
    [Fact]
    public async Task GetWeather_returns_text()
    {
        var clientToServer = new Pipe();
        var serverToClient = new Pipe();

        await using var server = McpServer.Create(
            new StreamServerTransport(
                clientToServer.Reader.AsStream(),
                serverToClient.Writer.AsStream()),
            new McpServerOptions
            {
                ToolCollection =
                [
                    McpServerTool.Create(
                        (string city) => $"{city}: 18°C",
                        new() { Name = "GetWeather" })
                ]
            });

        var serverTask = server.RunAsync();

        await using var client = await McpClient.CreateAsync(
            new StreamClientTransport(
                clientToServer.Writer.AsStream(),
                serverToClient.Reader.AsStream()));

        var tools = await client.ListToolsAsync();
        var tool = tools.Single(t => t.Name == "GetWeather");

        var result = await tool.CallAsync(new Dictionary<string, object?>
        {
            ["city"] = "Brussels"
        });

        Assert.False(result.IsError);
        var text = result.Content.OfType<TextContentBlock>().Single().Text;
        Assert.Equal("Brussels: 18°C", text);
    }
}

This style lets you assert on the exposed behaviour (what a real client sees), not internal details.

Testing tools that use sampling/elicitation/roots

Inject the MCP server, but supply mock client capabilities. With the in-memory pattern above, register handlers on the client:

await using var client = await McpClient.CreateAsync(clientTransport, new McpClientOptions
{
    Capabilities = new()
    {
        Sampling = new()
        {
            SamplingHandler = (req, progress, ct) =>
                Task.FromResult(new CreateMessageResult
                {
                    Content = [new TextContentBlock { Text = "MOCK SUMMARY" }]
                })
        },
        Elicitation = new()
        {
            ElicitationHandler = (req, ct) =>
                Task.FromResult(new ElicitResult
                {
                    Action = "accept",
                    Content = JsonSerializer.SerializeToNode(new { confirm = true })
                                .AsObject().ToDictionary(kv => kv.Key, kv => JsonDocument.Parse(kv.Value!.ToJsonString()).RootElement)
                })
        }
    }
});

Now your tool's server.SampleAsync / server.ElicitAsync calls hit deterministic mocks.

Unit tests at the DI layer

For pure logic with no MCP-specific behaviour, just test the class:

[Fact]
public void Echo_prepends_hello()
{
    Assert.Equal("hello world", EchoTool.Echo("world"));
}

The [McpServerTool] attribute doesn't affect runtime behaviour outside MCP wiring — your methods are just methods.

Running it from Claude Desktop / VS Code during development

For end-to-end "feels-like-the-real-thing" testing:

1. Run dotnet publish -c Release (or just dotnet build and use dotnet run). 2. Point Claude Desktop / VS Code at the binary or dotnet run --project .... See `transport-stdio.md` for the config snippets. 3. Restart the host. 4. Trigger the tool from chat.

When iterating, set up dotnet watch run --project ... so the server restarts on edit; the host typically reconnects on the next tool call.

CI

A typical CI pipeline:

- run: dotnet restore
- run: dotnet build --no-restore
- run: dotnet test --no-build --logger "trx;LogFileName=test-results.trx"

Nothing MCP-specific. The in-memory transport tests run anywhere dotnet test runs — no Node, no Docker.

Common diagnostic tricks

• "Tool isn't showing up": call client.ListToolsAsync() in a quick test and dump the names. If your tool isn't there, the registration is wrong.
• "LLM keeps misusing the tool": open Inspector and look at the schema/description as the LLM sees it. Most "the model is dumb" issues are actually missing [Description].
• "Sampling/elicitation throws 'method not supported'": the client doesn't advertise the capability. Either you're testing against a host that doesn't support it (Inspector supports both), or your in-memory client is missing the handler.
• "HTTP returns 404 for /": check app.MapMcp() is called and you're hitting the right path. MapMcp("/mcp") means the URL is http://host/mcp, not http://host/.

Tools

Tools are functions the LLM can call. In the C# SDK they're plain methods on a class marked [McpServerToolType], with each method marked [McpServerTool]. The SDK generates the JSON Schema from the method signature and [Description] attributes.

Anatomy of a tool

using System.ComponentModel;
using ModelContextProtocol.Server;

[McpServerToolType]
public class WeatherTools
{
    // Static or instance — both work. Instance methods get DI for the containing class.
    [McpServerTool, Description("Returns the current weather for a city.")]
    public static string GetWeather(
        [Description("City name, e.g. 'Brussels'")] string city,
        [Description("Units: 'celsius' or 'fahrenheit'")] string units = "celsius")
    {
        return $"{city}: 18°{units[0]}";
    }
}

Register it (one of):

.WithToolsFromAssembly()        // discovers all [McpServerToolType] in the calling assembly
.WithTools<WeatherTools>()      // explicit, single class

The tool name shown to the LLM is GetWeather (PascalCase converted to snake_case is not automatic — what you see is what you get unless you set Name explicitly).

Attribute options

[McpServerTool(
    Name = "get_weather",                 // override the tool name
    Title = "Get current weather",        // human-readable display name
    Destructive = false,                  // hint: tool modifies state irreversibly
    Idempotent = true,                    // hint: same args ⇒ same result
    OpenWorld = true,                     // hint: interacts with external systems
    ReadOnly = true                       // hint: doesn't mutate any state
)]
[Description("Returns the current weather for a city.")]
public static string GetWeather(...) { ... }

The behaviour hints (Destructive, Idempotent, OpenWorld, ReadOnly) are advisory — clients use them to decide things like auto-approval. They don't change runtime behaviour.

Async, cancellation, DI

[McpServerTool, Description("Fetches the latest commits for a repo.")]
public async Task<IEnumerable<Commit>> GetCommits(
    string owner,
    string repo,
    IGitHubClient github,                         // injected from DI
    CancellationToken cancellationToken)          // injected by the SDK
{
    return await github.GetCommitsAsync(owner, repo, cancellationToken);
}

The SDK recognises and special-cases these parameter types — they don't appear in the tool schema:

• IMcpServer / McpServer — the current server (used for ElicitAsync, SampleAsync, RequestRootsAsync, sending notifications).
• CancellationToken — propagated from the JSON-RPC request.
• RequestContext<CallToolRequestParams> — full request context if you need it.
• IServiceProvider — request-scoped service provider.
• Anything resolvable from DI that the SDK can recognise as not a primitive payload.

Everything else is treated as a JSON-RPC argument and goes into the schema.

Return types

The SDK serialises whatever you return into the appropriate content blocks. Practical guidance:

Returning structured data the LLM can act on

public record Forecast(string City, double TempC, string Conditions);

[McpServerTool, Description("Returns a 3-day forecast.")]
public static Forecast[] GetForecast(string city) =>
    new[]
    {
        new Forecast(city, 18.0, "sunny"),
        new Forecast(city, 16.5, "cloudy"),
        new Forecast(city, 14.2, "rain"),
    };

The SDK emits the array as both a JSON text block (for older clients) and structuredContent (for newer ones), and infers an output schema from Forecast.

Returning images / audio

[McpServerTool, Description("Generates a chart and returns it as a PNG.")]
public static ImageContentBlock RenderChart(string title)
{
    byte[] png = Renderer.Render(title);
    return ImageContentBlock.FromBytes(png, "image/png");
}

[McpServerTool, Description("Synthesises speech.")]
public static AudioContentBlock Speak(string text)
{
    byte[] wav = Tts.Synthesize(text);
    return AudioContentBlock.FromBytes(wav, "audio/wav");
}

Mixing content blocks

[McpServerTool, Description("Returns the chart and a caption.")]
public static IEnumerable<ContentBlock> RenderAnnotatedChart(string title)
{
    byte[] png = Renderer.Render(title);
    return new ContentBlock[]
    {
        new TextContentBlock { Text = $"Chart for: {title}" },
        ImageContentBlock.FromBytes(png, "image/png"),
        new TextContentBlock { Text = "Generated at " + DateTime.UtcNow.ToString("u") }
    };
}

Returning an embedded resource

Useful when the tool result is a document the user might want to reuse:

[McpServerTool, Description("Looks up a contract.")]
public static EmbeddedResourceBlock GetContract(string id)
{
    return new EmbeddedResourceBlock
    {
        Resource = new TextResourceContents
        {
            Uri = $"contracts://{id}",
            MimeType = "text/markdown",
            Text = LoadContract(id)
        }
    };
}

Errors

There are two flavours of error a tool can produce:

Tool-level errors (the LLM can read and recover from these)

Throw any exception — the SDK catches it and returns a CallToolResult with IsError = true and the exception message in a text block:

[McpServerTool, Description("Divides a by b.")]
public static double Divide(double a, double b)
{
    if (b == 0)
        throw new ArgumentException("Cannot divide by zero.");
    return a / b;
}

You can also build the result explicitly:

[McpServerTool, Description("…")]
public static CallToolResult Foo(...)
{
    return new CallToolResult
    {
        IsError = true,
        Content = [new TextContentBlock { Text = "Detailed error explanation for the LLM." }]
    };
}

Protocol-level errors (the call is rejected before the LLM sees a result)

Use McpException (or McpProtocolException with an explicit error code) for things like bad arguments:

[McpServerTool, Description("…")]
public static string Process(string input)
{
    if (string.IsNullOrWhiteSpace(input))
        throw new McpProtocolException("Missing required input", McpErrorCode.InvalidParams);
    return $"Processed: {input}";
}

Heuristic: if the LLM should try again with different arguments, throw a regular exception so it gets a tool error. If the call is malformed in a way the LLM can't fix, throw McpProtocolException.

Notifying clients of tool list changes

If your tools come and go at runtime (e.g. plugin loaded, user logged in), notify the client:

await server.SendNotificationAsync(
    NotificationMethods.ToolListChangedNotification,
    new ToolListChangedNotificationParams(),
    cancellationToken);

Requires a stateful transport (STDIO or stateful HTTP).

Common pitfalls

• Forgetting `[McpServerToolType]` on the class. The method-level [McpServerTool] alone won't be discovered by WithToolsFromAssembly.
• Vague descriptions. [Description("Gets data")] makes the LLM guess. Spend a sentence describing what the tool does, when to call it, and what it returns.
• Big payloads. Tools that return megabytes of JSON eat the model's context. Trim or paginate. For binary blobs, return an EmbeddedResourceBlock so the host can decide how to render it.
• Hiding errors. Returning "failed" as a string looks like success to the SDK. Throw the exception or set IsError = true.

Streamable HTTP transport (ASP.NET Core)

Streamable HTTP is the modern remote transport. A single endpoint accepts JSON-RPC over HTTP POST and (optionally) streams responses back as Server-Sent Events when the server has more than one message to send.

SSE-only is deprecated. The legacy "HTTP+SSE" transport (separate POST endpoint + GET SSE endpoint) is gone from new clients. Use Streamable HTTP. Only enable legacy SSE (EnableLegacySse = true) if you must support a known-old client, and document why.

When to choose HTTP

• Multi-tenant or remote-hosted server.
• Auth via OAuth / API gateway in front.
• Horizontally scaled deployments (with Stateless = true).
• Containers, Azure Container Apps, Kubernetes, etc.

For local single-user scenarios, STDIO is simpler.

Minimal server

dotnet new web -n MyHttpServer -f net10.0
cd MyHttpServer
dotnet add package ModelContextProtocol.AspNetCore

// Program.cs
using ModelContextProtocol.Server;
using System.ComponentModel;

var builder = WebApplication.CreateBuilder(args);

builder.Services
    .AddMcpServer()
    .WithHttpTransport(options =>
    {
        // Stateless = true: each request is independent, no Mcp-Session-Id tracking.
        // Required for horizontal scaling without sticky sessions.
        // Disables server-to-client features (sampling, elicitation, roots, unsolicited notifications).
        options.Stateless = true;
    })
    .WithToolsFromAssembly();

var app = builder.Build();

app.MapMcp();              // mounts the MCP endpoints at "/"
// app.MapMcp("/mcp");     // or under a path prefix

app.Run("http://localhost:3001");

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

Stateless vs. stateful — the most important decision

Rule: if the user wants any of ElicitAsync, SampleAsync, RequestRootsAsync, or to push log/notification messages, do not set Stateless = true. The calls will fail at runtime with no transport to deliver them on.

Endpoint shape

MapMcp(pattern = "") creates a route group at pattern and maps:

• POST — accepts JSON-RPC requests/responses/notifications. Returns either a JSON response or an SSE stream depending on Accept header and whether multiple messages need to flow back.
• GET — used by stateful sessions for the server-to-client SSE channel.
• DELETE — terminates a stateful session.

Default pattern is the root (/). To put MCP under /mcp/v1:

app.MapMcp("/mcp/v1");

Match this on the client side (Endpoint = new Uri("https://host/mcp/v1")).

Per-session configuration (HttpContext access)

When you need to vary server behaviour per HTTP request (auth, tenant, headers), use the ConfigureSessionOptions callback:

builder.Services
    .AddMcpServer()
    .WithHttpTransport(options =>
    {
        options.ConfigureSessionOptions = async (httpContext, mcpOptions, ct) =>
        {
            var tenantId = httpContext.Request.Headers["X-Tenant"].ToString();
            mcpOptions.ServerInstructions = $"Tenant: {tenantId}";
            // mutate any McpServerOptions fields per-session
        };
    });

Inside a tool, you can also inject IHttpContextAccessor if AddHttpContextAccessor() is registered. See the `AspNetCoreMcpPerSessionTools` sample.

Authentication

The MCP endpoint is just an ASP.NET Core endpoint — apply standard middleware:

builder.Services
    .AddAuthentication("Bearer")
    .AddJwtBearer(/* configure */);
builder.Services.AddAuthorization();

var app = builder.Build();

app.UseAuthentication();
app.UseAuthorization();

app.MapMcp().RequireAuthorization();   // protect the endpoint

For OAuth flows where the MCP server is the resource server, follow the MCP authorization spec. The `ProtectedMcpServer` sample shows a working setup with discovery endpoints.

For machine-to-machine, an API key middleware is fine:

app.Use(async (ctx, next) =>
{
    if (ctx.Request.Headers["X-Api-Key"] != Configuration["ApiKey"])
    {
        ctx.Response.StatusCode = StatusCodes.Status401Unauthorized;
        return;
    }
    await next();
});

CORS (when the client is in-browser)

builder.Services.AddCors(o => o.AddDefaultPolicy(p =>
    p.WithOrigins("https://my-host.example.com")
     .AllowAnyHeader()
     .AllowAnyMethod()
     .AllowCredentials()));
// ...
app.UseCors();
app.MapMcp();

Health checks and observability

Add the standard ASP.NET Core probes; the MCP endpoint shouldn't be the liveness check.

builder.Services.AddHealthChecks();
// ...
app.MapHealthChecks("/healthz");

The SDK emits OpenTelemetry traces (Activity per tool call) and metrics. Wire them up if the user has an OTel pipeline:

builder.Services
    .AddOpenTelemetry()
    .WithTracing(t => t.AddSource("ModelContextProtocol").AddOtlpExporter())
    .WithMetrics(m => m.AddMeter("ModelContextProtocol").AddOtlpExporter());

Deployment notes

• Containerise normally. No special MCP-specific Dockerfile — it's just an ASP.NET Core app.
• Behind a reverse proxy (nginx, Azure Front Door, AWS ALB), make sure SSE buffering is disabled for the MCP path. nginx: proxy_buffering off;. Without this, streaming responses are batched into one slow blob.
• Timeouts. The client may keep an SSE connection open for a long time. Set proxy idle timeout high (e.g. 5+ minutes) for stateful deployments; less critical for stateless.
• Azure Container Apps / App Service work out of the box; both support long-lived HTTP responses.

Enabling legacy SSE (compatibility only)

builder.Services
    .AddMcpServer()
    .WithHttpTransport(options =>
    {
        options.EnableLegacySse = true;
#pragma warning disable MCP9004
        options.Stateless = false; // SSE requires stateful mode
#pragma warning restore MCP9004
    })
    .WithToolsFromAssembly();

Only do this if the user has a documented client that hasn't migrated. New deployments should not enable it.

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 (sampling, elicitation, 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
dotnet add package Microsoft.Extensions.Hosting

// 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) in the initialize response. 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();