skilld
All skills
github avatar

/dotnet-mcp-builder

@aa01464 official
by githubgithub/awesome-copilot40k stars
5,040

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.

Ask your Agent

Use this Skill: https://skilld.dev/gh/github/awesome-copilot/dotnet-mcp-builder

This session only. Nothing lands on disk.

referencespackages.md

≈1.3k tokens on demand. Your agent reads this file only when SKILL.md points to it.

NuGet packages and target frameworks

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

Package When to use it Brings in
ModelContextProtocol Default for STDIO servers and most projects Core + Microsoft.Extensions.Hosting integration, attribute discovery (AddMcpServer, WithToolsFromAssembly, etc.)
ModelContextProtocol.AspNetCore HTTP (Streamable) servers hosted in ASP.NET Core The above + WithHttpTransport and MapMcp
ModelContextProtocol.Core Pure clients, custom hosts, low-level scenarios where you don't want the Microsoft.Extensions.* dependencies Just the protocol + transports + low-level McpServer.Create / McpClient.CreateAsync
ModelContextProtocol.Extensions.Tasks (2.x) Long-running task support (the MCP Tasks extension) Production replacement for the experimental 1.4.x Tasks APIs; register via WithTasks(...)
ModelContextProtocol.Extensions.Apps (2.x) MCP Apps — interactive UI rendered in the host Typed [McpAppUi] attribute + .WithMcpApps() registration replacing the hand-rolled _meta wiring of 1.x; you still serve the UI as a ui:// resource, and the APIs are experimental (MCPEXP003) — see mcp-apps.md

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 mid-2026, the stable line is 2.x (2.2.0 is current at time of writing), aligned with the MCP 2026-07-28 spec. 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. The 1.x line still compiles and interoperates, but predates the v2 changes (stateless-by-default HTTP, discovery-first negotiation, roots/sampling/logging deprecations, the Tasks/Apps extension packages) — prefer 2.x for new projects.

Upgrading 1.x → 2.0 (highlights, not exhaustive): stable v1.x APIs keep working; the deprecated capabilities (roots, sampling, logging) are now [Obsolete] with MCP9005 warnings, experimental APIs moved (the 1.4.x Tasks surface → ModelContextProtocol.Extensions.Tasks), and several behaviors flipped (HttpServerTransportOptions.Stateless now defaults to true; non-object tool results emit raw structuredContent values; Tool.inputSchema is required on deserialization). OAuth also changed at runtime — AuthorizationRedirectDelegate → ClientOAuthOptions.AuthorizationCallbackHandler, RFC 9207 issuer validation, mandatory PKCE S256 in metadata, application_type in dynamic registration — and SSE transport failures now propagate the underlying HttpRequestException/TimeoutException. Before upgrading, read the full v2.0.0 release notes.

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 --version 2.2.0
dotnet add package Microsoft.Extensions.Hosting --version 10.0.11

HTTP (Streamable) server

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

(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 --version 2.2.0

Optional but commonly useful

Package Why
Microsoft.Extensions.AI Provides IChatClient, ChatMessage, ChatRole, ChatOptions — the abstractions used by AsSamplingChatClient() and by prompt return types.
Microsoft.Extensions.AI.Abstractions Pulled in transitively but worth knowing about for types like DataContent, TextContent.
OpenTelemetry.Extensions.Hosting The SDK emits OTel traces and metrics for tool calls — wire them up if the user has an observability story.

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.

Source: SKILL.md on GitHub

Third-party checks

No alerts15d3 checks · Risk SAFE
  • Gen Agent Trust Hub15d

    The skill provides technical guidance and code references for building Model Context Protocol (MCP) servers and clients using the official C#/.NET SDK. It includes security best practices for resource access and follows standard development patterns.

  • Socket15d

    No alerts

  • Snyk15d

    Risk: LOW · No issues

Provenance

Signed by skilld at aa01464. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 20 hours ago.

Activeupdated 2 months ago

Topics

  • MCP
  • dotnet
  • csharp
  • model-context-protocol
  • stdio
  • http
  • tools
  • prompts
  • resources
  • streaming

README badge

README badge for github/awesome-copilot/dotnet-mcp-builder

What it does

Builds Model Context Protocol servers in C# / .NET against the stable 1.x SDK, covering STDIO and HTTP transports, tools, prompts, resources, sampling, elicitation, MCP Apps, and debugging. Targets the specific pitfalls that cause breakage: stale preview package versions, stdout pollution in STDIO mode, stateless HTTP misconfiguration, and missing primitive registration in DI.

Generated from the current SKILL.md.

Frequently asked

Does this skill work with preview versions of the ModelContextProtocol NuGet packages?
No. The skill targets stable 1.x packages only. Preview versions (0.3, 0.4) have breaking differences and won't compile against current samples. Always pin the latest 1.x release.
Can I use stateless HTTP transport with sampling, elicitation, or server-initiated notifications?
No. Stateless HTTP breaks those features at runtime because it cannot maintain bidirectional communication. Use stateful HTTP or STDIO if you need server-to-client capabilities.
What should I do if my STDIO server isn't working?
First check that nothing is writing to stdout — configure `LogToStandardErrorThreshold = LogLevel.Trace` and remove any `Console.WriteLine` calls, since stdout is the JSON-RPC channel. Also verify tools and prompts are registered with `.WithToolsFromAssembly()` or equivalent.
Does this skill cover building MCP servers in other languages like Python or TypeScript?
No. This skill is C#/.NET only. It skips MCP work in other languages.
Can I write a .NET program that consumes an MCP server instead of building one?
Yes. Load `references/client.md` for guidance on writing a basic .NET MCP client that calls an existing server.

Generated from the current SKILL.md. These answers refresh after source changes.