dotnet-mcp

MCP C# SDK for .NET

Trigger On

• building or consuming MCP servers from a .NET application or library
• choosing between stdio and HTTP transport for MCP
• exposing tools, resources, prompts, completions, or logging to an MCP host
• connecting a .NET app to an existing MCP server and passing discovered tools into IChatClient
• bootstrapping a minimal MCP client/server from the .NET AI quickstarts or publishing a server to the MCP Registry
• implementing capability-aware flows such as roots, sampling, elicitation, subscriptions, or session resumption

Use This Skill Instead Of

• Use dotnet-mcp when protocol interoperability is the requirement.
• Use dotnet-microsoft-extensions-ai when you only need model/provider abstraction or local tool orchestration without the MCP wire protocol.
• Use dotnet-microsoft-agent-framework when the main problem is agent orchestration; combine it with dotnet-mcp only when those agents must consume or expose MCP endpoints.
• Use the .NET AI quickstarts for the very first vertical slice, then come back here to harden transport, capability negotiation, publishing, and host interoperability.

Documentation

• MCP C# SDK overview
• Getting Started
• API reference
• Conceptual docs
• Versioning policy
• Experimental APIs
• MCP C# SDK repository
• Model Context Protocol specification

References

Load only what the task needs:

• references/patterns.md - current server/client patterns, transports, capabilities, filters, and chat-client integration
• references/security.md - safe error handling, auth boundaries, stdio logging hygiene, and defensive tool/resource patterns

Package Selection

Transport Selection

flowchart LR
    A["Need MCP interoperability in .NET"] --> B{"Role?"}
    B -->|"Expose MCP surface"| C{"Where will it run?"}
    B -->|"Consume an MCP server"| D{"Transport?"}
    C -->|"Local child process"| E["ModelContextProtocol\nAddMcpServer()\nWithStdioServerTransport()"]
    C -->|"Remote HTTP endpoint"| F["ModelContextProtocol.AspNetCore\nAddMcpServer()\nWithHttpTransport()\nMapMcp()"]
    D -->|"stdio"| G["StdioClientTransport\nMcpClient.CreateAsync()"]
    D -->|"HTTP"| H["HttpClientTransport\nAutoDetect or StreamableHttp"]
    E --> I["Register tools/resources/prompts"]
    F --> I
    G --> J["Check ServerCapabilities\nbefore optional features"]
    H --> J

Workflow

1. Pick the package and transport first.

   • Local child-process server: ModelContextProtocol + WithStdioServerTransport().
   • Remote server: ModelContextProtocol.AspNetCore + WithHttpTransport() + MapMcp().
   • Client-only app: start with ModelContextProtocol or ModelContextProtocol.Core.
   • Registry distribution: pair a minimal server with the MCP Registry publishing flow only after the server contract is stable.

2. Model the MCP surface explicitly.

   • Tools: [McpServerToolType] + [McpServerTool]
   • Resources: [McpServerResourceType] + [McpServerResource]
   • Prompts: [McpServerPromptType] + [McpServerPrompt]
   • Use custom handlers or filters only for cross-cutting behavior, protocol extensions, or advanced routing.

3. Prefer attribute discovery for straightforward servers.

using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;
using ModelContextProtocol.Server;
using System.ComponentModel;

var builder = Host.CreateApplicationBuilder(args);
builder.Logging.AddConsole(options =>
{
    options.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}";
}

4. For HTTP servers, use the ASP.NET Core transport and map the endpoint directly.

using ModelContextProtocol.Server;
using System.ComponentModel;

var builder = WebApplication.CreateBuilder(args);

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

var app = builder.Build();
app.MapMcp("/mcp");
app.Run();

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

5. When consuming a server, use McpClient.CreateAsync(...) and stay capability-aware.

using ModelContextProtocol.Client;
using ModelContextProtocol.Protocol;

var transport = new StdioClientTransport(new StdioClientTransportOptions
{
    Name = "Everything",
    Command = "npx",
    Arguments = ["-y", "@modelcontextprotocol/server-everything"],
});

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

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

if (client.ServerCapabilities.Prompts is not null)
{
    var prompts = await client.ListPromptsAsync();
}

6. Treat optional features as negotiated capabilities, not assumptions.

   • Client capabilities: configure McpClientOptions.Capabilities for roots, sampling, and elicitation.
   • Server capabilities are inferred from registered features.
   • Check client.ServerCapabilities before using completions, logging, prompt list-change notifications, or resource subscriptions.
   • Use client.NegotiatedProtocolVersion or server.NegotiatedProtocolVersion only when version-specific behavior matters.

7. Keep HTTP guidance current.

   • Streamable HTTP is the recommended transport for remote servers.
   • MapMcp() also serves SSE compatibility endpoints for older clients.
   • HTTP clients can use AutoDetect by default, or force StreamableHttp / Sse.
   • Session resumption is available for Streamable HTTP through McpClient.ResumeSessionAsync(...).

8. Treat the .NET AI MCP quickstarts as bootstrap examples.

   • build-mcp-client and build-mcp-server are good starting points when the surrounding app is still MEAI-centric.
   • publish-mcp-registry is the distribution step, not the design step. Stabilize the protocol surface before publishing.

9. Respect current error and serialization rules.

   • Tool exceptions normally come back as CallToolResult.IsError == true.
   • Throw McpProtocolException only for protocol-level JSON-RPC failures.
   • McpClientTool inherits from AIFunction, so discovered tools can be passed directly into IChatClient.
   • Experimental APIs use MCPEXP... diagnostics; suppress them intentionally, not globally by accident.
   • If you use a custom JsonSerializerContext, prepend McpJsonUtilities.DefaultOptions.TypeInfoResolver so MCP protocol types keep the SDK's contract.

Anti-Patterns To Avoid

Deliver

• a correctly packaged MCP server or client that matches the deployment topology
• explicit tool/resource/prompt definitions with descriptions and bounded payloads
• capability-aware handling for optional MCP features
• validation notes for transport, auth boundary, and host/client interoperability

Validate

• chosen package matches the topology: Core, ModelContextProtocol, or AspNetCore
• stdio servers do not write logs or diagnostics to stdout
• HTTP servers use MapMcp() and are tested at the final route, for example /mcp
• tools, resources, and prompts use current [McpServer*] attributes or documented handler/filter alternatives
• client code checks ServerCapabilities before using subscriptions, completions, logging, or prompt/resource list-change flows
• Streamable HTTP is the default for new remote servers; SSE is used only for legacy compatibility
• experimental APIs and custom serialization settings are reviewed intentionally rather than copied blindly