MCP C# SDK 2.2.0: Stateless HTTP and Hybrid Migration Guide

The short answer

The official Model Context Protocol (MCP) C# SDK reached 2.2.0 on August 13, 2026, building on the major 2.0.0 release from July 28. The practical change in 2.2.0 is a hybrid HTTP serving mode: one endpoint can support clients using both the older 2025-11-25 protocol revision and the newer 2026-07-28 revision. The release also fixes a malformed header-decoding edge case.

For .NET teams, the upgrade is less about adding a flashy agent feature and more about making MCP migration survivable. New services can use stateless HTTP by default, while existing stateful clients can continue working during a staged rollout. That matters when an MCP server sits behind ordinary load balancers, gateways, or serverless infrastructure.

The safe adoption path is to upgrade in a test environment, explicitly decide whether each endpoint should be stateless, stateful, or hybrid, and verify authorization, protocol negotiation, tool schemas, and observability before production traffic moves.

What changed in MCP C# SDK 2.2.0

The official GitHub release lists two behaviorally important changes:

• HttpServerSessionMode adds hybrid stateful/stateless HTTP serving.
• A malformed base64 wrapper no longer causes McpHeaderEncoder.DecodeValue to throw unexpectedly.

The hybrid mode is designed for a migration reality: not every MCP client upgrades at the same time. A server can expose a compatible path while clients using the 2025-11-25 and 2026-07-28 protocol revisions share the endpoint.

That capability follows the much larger 2.0.0 release. Version 2.0 aligned the SDK with the 2026-07-28 specification, changed HTTP to stateless by default, added discovery-first negotiation, introduced multi-round-trip requests, standardized headers, and moved Tasks into a dedicated extension package. It also strengthened OAuth and PKCE validation.

Why stateless HTTP matters

The MCP community’s move toward stateless HTTP addresses a deployment problem. Stateful remote MCP servers often need sticky sessions, shared session storage, long-lived streams, or special routing. A stateless request can be handled by any healthy instance, which makes ordinary HTTP infrastructure more useful.

Cloudflare’s explanation of the next generation of MCP describes the operational goal clearly: MCP servers can run without stateful infrastructure, reducing moving parts for remote deployments. Stateless does not mean “security-free” or “memory-free”; it means the protocol transport does not require a server-side session for every request. Application state, authentication state, idempotency, and audit records still need deliberate designs.

Architecture: choosing a transport mode

Use stateless mode for new HTTP services when each request can carry the context required to authorize and execute the operation. Use stateful mode when your existing client or interaction requires a long-lived session. Use hybrid mode during migration when you cannot coordinate upgrades across all clients.

diagram

Figure: a migration-oriented request flow. The diagram is an original editorial illustration based on the protocol and SDK behavior documented by the MCP project; it is not an official Microsoft architecture diagram.

A useful rule is to keep the transport decision separate from business logic. Your tools should validate inputs and permissions regardless of whether the request arrived through a stateful or stateless path. That separation makes it easier to remove the compatibility path later.

Version comparison for .NET teams

The table is a compatibility planning aid, not a benchmark. The release pages do not claim a specific latency or throughput gain, so teams should measure their own workload rather than inventing a performance number.

Prerequisites and upgrade plan

Target a supported .NET application, add the official ModelContextProtocol package at the version you have tested, and use the matching ASP.NET Core integration package when your server is hosted in ASP.NET Core. The MCP C# SDK repository is the canonical place to confirm package names, samples, and current API details.

Before changing production traffic:

1. Create a branch that upgrades the core and ASP.NET Core MCP packages together.
2. Record the protocol revisions your clients actually negotiate.
3. Search for stateful transport options, SSE endpoint assumptions, custom session stores, and sticky-routing rules.
4. Review Tasks, Roots, Sampling, and Logging usage. The 2026-07-28 specification deprecates some older API surfaces, so warnings should be treated as migration work rather than hidden.
5. Add integration tests for discovery, legacy fallback, stateless requests, tool errors, authorization failures, and malformed headers.
6. Deploy the hybrid mode behind a feature flag or a separate route.
7. Observe real traffic before removing the compatibility path.

A minimal test matrix

Security and privacy implications

Stateless transport changes routing, not trust boundaries. Every request still needs authentication, authorization, input validation, rate limiting, and audit logging. Do not put bearer tokens, tenant secrets, or sensitive conversation state into casually logged headers or query strings.

The 2.0 release’s OAuth changes are especially relevant. Issuer validation and PKCE S256 requirements are protections, not obstacles to work around. If an authorization server’s metadata is inconsistent, fix the metadata or adapter. Suppressing a warning can be a temporary migration tactic; disabling validation is not a safe production strategy.

For tool servers, treat the transport as an untrusted boundary. Validate tenant ownership server-side, scope credentials to the individual operation, enforce timeouts, and make destructive tools require explicit authorization. The broader MCP tool-server threat-modeling guide is a useful companion for reviewing confused-deputy, SSRF, excessive-permission, and audit risks.

Statelessness also affects observability. A request ID, authenticated principal, tenant ID, tool name, outcome, latency, and policy decision should be available in structured logs or traces. Do not assume a server session ID is the only way to correlate activity. If your application needs a conversation or workflow identifier, create one at the application layer and define its retention policy.

Common migration failures

The server is stateless but the application is not

A server that stores in-progress workflows only in process memory will fail when a later request lands on another instance. Move durable workflow state to a database, queue, or state service, or keep the endpoint stateful until the application is redesigned.

Legacy clients appear to hang

Check whether the endpoint still supports the legacy handshake and whether a proxy is buffering or blocking streaming responses. Confirm that the hybrid configuration is applied to the actual production route, not only to a development endpoint.

OAuth works locally but fails in production

Compare issuer metadata, redirect URIs, forwarded-host handling, and PKCE support. Reverse proxies can change the apparent scheme and host. Correct proxy trust configuration rather than weakening issuer checks.

Tool calls duplicate side effects

Retries become more visible when requests can be routed freely. Add idempotency keys for payments, writes, deployment actions, and other irreversible operations. A tool should be safe to retry or should return a clear “already processed” result.

A tool schema fails after the upgrade

The 2.0 release requires inputSchema during deserialization. Update hand-written fixtures, proxy transformations, and test doubles so they emit a valid schema, even when the tool accepts an empty object.

Should you upgrade now?

Upgrade now in a staging environment if you operate .NET MCP servers, especially if you are planning to move from sticky-session hosting to ordinary load balancing. Version 2.2.0 gives you a practical bridge for mixed client fleets, while the 2.0 protocol alignment provides the long-term stateless direction.

Do not treat 2.2.0 as a reason to flip every endpoint to stateless overnight. The correct sequence is inventory, test, hybrid rollout, observe, and then simplify. Teams with only new 2026-07-28 clients can usually start with stateless mode; teams with unknown client versions should begin with hybrid mode and set a removal date for compatibility.

If your service is primarily an agent backend rather than an MCP server, compare this transport work with the governance and sandbox controls in the OpenAI Agents SDK sandbox guide and the production patterns in the agentic RAG guide. MCP transport reliability is only one part of a safe agent architecture.

FAQ

Is MCP C# SDK 2.2.0 a breaking release?

The 2.2.0 release is a minor update after 2.0.0. The major breaking behavior arrived in 2.0.0, including stateless-by-default HTTP and changes around deprecated APIs, Tasks, OAuth validation, and tool schemas. Read the release notes and run your own integration tests before upgrading.

Can stateful and stateless clients share one endpoint?

That is the purpose of the HttpServerSessionMode capability added in 2.2.0. Confirm the exact configuration and negotiation behavior in the SDK documentation for your package version, then test both protocol revisions through the same route.

Does stateless MCP remove the need for a database?

No. It removes a protocol-level requirement for a server session. Your application may still need a database for users, permissions, workflow state, idempotency keys, billing, audit records, and long-running tasks.

Does the release include a performance benchmark?

The official 2.2.0 release notes describe hybrid serving and header-decoding fixes, not a universal latency or throughput benchmark. Measure connection setup, tool execution, proxy behavior, and cost on your own infrastructure.

Conclusion

MCP C# SDK 2.2.0 is a migration release with production value: it lets .NET teams adopt the stateless 2026-07-28 direction without requiring every client to upgrade on the same day. The safest implementation is explicit and incremental—keep transport compatibility at the edge, keep authorization in every tool, persist application state outside the process, and use tests to prove that requests remain correct when they move between instances.

Sources and visual credits

• MCP C# SDK v2.2.0 release notes — official primary source.
• MCP C# SDK v2.0.0 release notes — official primary source.
• The next generation of MCP — Cloudflare engineering explanation of stateless MCP.
• MCP C# SDK repository — official code and documentation.
• Original Mermaid architecture diagram and comparison table created for this article; no external screenshot or benchmark visual used.