/mcp

name: mcp
description: "Build or consume Model Context Protocol (MCP) servers and clients in .NET using the official MCP C# SDK, including stdio, Streamable HTTP, tools, prompts, resources, and capability negotiation. USE FOR: .NET MCP servers or clients; stdio versus HTTP transport choices; tools, resources, prompts, completions, and capability negotiation. DO NOT USE FOR: unrelated stacks; generic tasks that do not need this specific guidance. INVOKES: inspect the repository context, edit targeted files, and run relevant build, test, lint, or validation commands when changes are made."
compatibility: "Requires the official MCP C# SDK packages (`ModelContextProtocol.Core`, `ModelContextProtocol`, or `ModelContextProtocol.AspNetCore`) on .NET 8+; current guidance targets the v2.2 SDK and MCP 2026-07-28."

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, session resumption, or enterprise managed authorization

Use This Skill Instead Of

• Use `mcp` when **protocol interoperability** is the requirement.
• Use `microsoft-extensions-ai` when you only need model/provider abstraction or local tool orchestration without the MCP wire protocol.
• Use `microsoft-agent-framework` when the main problem is agent orchestration; combine it with `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](https://csharp.sdk.modelcontextprotocol.io/)
• [Getting Started](https://csharp.sdk.modelcontextprotocol.io/concepts/getting-started.html)
• [API reference](https://csharp.sdk.modelcontextprotocol.io/api/ModelContextProtocol.html)
• [Conceptual docs](https://csharp.sdk.modelcontextprotocol.io/concepts/index.html)
• [Versioning policy](https://csharp.sdk.modelcontextprotocol.io/versioning.html)
• [Experimental APIs](https://csharp.sdk.modelcontextprotocol.io/experimental.html)
• [MCP C# SDK repository](https://github.com/modelcontextprotocol/csharp-sdk)
• [Model Context Protocol specification](https://modelcontextprotocol.io/specification/)

References

Load only what the task needs:

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

Package Selection

| Package | Choose when | |---------|-------------| | `ModelContextProtocol.Core` | You only need a client or low-level server APIs and want the smallest dependency set. | | `ModelContextProtocol` | You want the main SDK package with hosting, DI, attribute discovery, and stdio server support. Start here for most projects. | | `ModelContextProtocol.AspNetCore` | You are hosting a remote MCP server in ASP.NET Core over HTTP. This includes the main package. |

Transport Selection

| Transport | Use when | Notes | |-----------|----------|-------| | `StdioClientTransport` / `WithStdioServerTransport()` | The MCP server should run as a local child process. | Best for local tooling and editor/agent integrations. | | `HttpClientTransport` + `HttpTransportMode.StreamableHttp` | The server is remote or should be reachable over HTTP. | Recommended HTTP transport; supports streaming and session resumption. | | `HttpTransportMode.Sse` | You must connect to an older SSE-only server. | Legacy compatibility only; do not choose this for new servers. |

Current v2.2 Notes

• The August 2026 `.NET AI` MCP documentation separates a getting-started hub, client and server quickstarts, MCP Registry publishing, and a server-resource index. Use those pages to bootstrap a vertical slice, then return to the C# SDK docs here for exact transport, capability, authorization, and lifecycle behavior.
• SDK `v2.0.0` aligns with MCP `2026-07-28`: HTTP is stateless by default, clients negotiate with `server/discover` before falling back to legacy `initialize`, Tasks move to `ModelContextProtocol.Extensions.Tasks`, and Roots, Sampling, and Logging are deprecated for the new protocol. Set `HttpServerTransportOptions.Stateless = false` only for an intentional stateful compatibility requirement.
• SDK `v2.1.0` adds an opt-in `subscriptions/listen` server handler, keeps AutoDetect usable after a provisional SSE failure, preserves HTTP status codes across target frameworks, and falls back to `initialize` when `server/discover` fails at the HTTP layer. Add custom notification streams only when both peers negotiate the extension.
• SDK `v2.2.0` adds `HttpServerSessionMode` so one ASP.NET Core endpoint can serve stateful and stateless clients across the MCP `2025-11-25` and `2026-07-28` protocol versions. Choose the mode explicitly, test both negotiated paths when compatibility matters, and upgrade before working around malformed percent-encoded request headers because the release fixes that decoding failure.
• Before moving from `v1.4.x`, update structured-result consumers to accept non-object values directly, require `Tool.inputSchema` in custom payloads, move Tasks to the extension package, and test PKCE S256 plus issuer validation in OAuth metadata.
• Enterprise managed authorization now has an SDK surface through `IdentityAssertionGrantProvider` for the Identity Assertion Authorization Grant flow. Use it only when the enterp