v0.4.1-preview.1

Breaking Changes

The v0.4.1-preview.1 release includes breaking changes included in #892 and #969.

1. #892 audits and standardizes MCP protocol types for consistency, including API changes for:
2. Property mutability
3. Required properties
4. Collection types used for properties
5. #969 implements SEP-1330: Elicitation Enum Schema Improvements and Standards Compliance, which involved a breaking change to the specification:
6. EnumSchema is marked [Obsolete] using the default CS0618 diagnostic, and it becomes an alias for LegacyTitledEnumSchema, which is also marked as [Obsolete] using the default CS0618 diagnostic

Path to 1.0.0

We are working toward the first stable version of the C# SDK as version 1.0.0, which will have compliance with Version 2025-11-25 of the MCP specification. We will publish at least one more pre-release version of the SDK before declaring the stable version, and breaking changes to Remove obsolete interfaces and extension methods (#774) are expected as part of stablizing the API.

Refer to the new C# SDK Versioning documentation for information regarding our versioning, breaking change, and support approaches once we publish the 1.0.0 release.

What's Changed

• Add default value support for all primitive types in elicitation schemas (SEP-1034) by @Copilot in #924
• Audit protocol types by @MackinnonBuck in #892
• Implement SEP-986: Specify Format for Tool Names by @stephentoub in #945
• Add public constructors to McpClient types for reusing cached definitions by @Copilot in #938
• Tweak how McpClientTool.InvokeAsync exposes some content by @stephentoub in #941
• Ignore unexpected properties when deserializing a ContentBlock by @jeffhandley in #956
• Remove prerelease requirement from global.json by @eiriktsarpalis in #961
• Add Description property to Implementation type per MCP spec by @Copilot in #966
• Remove TODOs related to AllowOutOfOrderMetadataProperty workarounds. by @eiriktsarpalis in #977
• Make JsonRpcMessageWithId.RequestId non-required by @MackinnonBuck in #984
• Implement SEP-1330: Standards-compliant enum schemas for elicitation by @Copilot in #969
• Add production-ready incremental source generator for automatic Description attributes from XML comments by @Copilot in #899
• Add tools support to sampling by @stephentoub in #976
• Use JsonElement.Parse for string-to-JsonElement deserialization by @Copilot in #1002
• Fix race condition in StdioClientTransport on .NET Framework by @Copilot in #996
• Tokens can be cached beyond the lifetime of the (http) transport. by @halllo in #834
• Add ability for client to resume session by @halter73 in #1029

Documentation Updates

• Update ModelId in QuickStartClient to non-deprecated version by @PederHP in #926
• Add file-based MCP server sample by @PederHP in #931
• Align error handling documentation with SEP-1303 by @Copilot in #967
• Fix a couple issues in the client sample readme by @ericstj in #994
• Fix documentation typos and incorrect type references by @Copilot in #993
• Introduce versioning, breaking changes, and support document by @jeffhandley in #986
• Address additional feedback on Versioning doc by @jeffhandley in #999
• Tweak the file-based MCP server sample by @eiriktsarpalis in #1019
• Writing style edits by @gewarren in #1024

Repository Infrastructure Updates

• Update Microsoft.Extensions.AI packages to version 9.10.1 by @Copilot in #916
• Update to .NET SDK to 10.rc2 by @eiriktsarpalis in #883
• Bump danielpalme/ReportGenerator-GitHub-Action from 5.4.17 to 5.4.18 by @dependabot[bot] in #920
• Bump actions/upload-artifact from 4.6.2 to 5.0.0 by @dependabot[bot] in #918
• Bump actions/download-artifact from 5.0.0 to 6.0.0 by @dependabot[bot] in #919
• fixed donet version from 10.0.100-rc.1.25451.107 to 10.0.100-rc.2 by @eduardomb-aw in #927
• Update to .NET 10.x packages by @stephentoub in #957
• Fix tests in Dev Container by @halter73 in #965
• Update to MTP by @Youssef1313 in #958
• Bump actions/checkout from 5.0.0 to 5.0.1 by @dependabot[bot] in #973
• Bump danielpalme/ReportGenerator-GitHub-Action from 5.4.18 to 5.5.0 by @dependabot[bot] in #972
• Bump the opentelemetry-testing group with 6 updates by @dependabot[bot] in #974
• Revert "Update to MTP" by @eiriktsarpalis in #989
• Bump the serilog-testing group with 2 updates by @dependabot[bot] in #992
• Bump the testing-frameworks group with 3 updates by @dependabot[bot] in #991
• Skip flaky test on Mono where stderr callbacks are unsupported by @Copilot in #980
• Revert "Revert "Update to MTP"" by @Youssef1313 in #990
• Add Microsoft.CodeAnalysis.* to dependabot ignore list by @Copilot in #1009
• Revert "Update to MTP (#958)" by @halter73 in #1011
• Bump the testing-frameworks group with 3 updates by @dependabot[bot] in #1013
• Bump the serilog-testing group with 1 update by @dependabot[bot] in #1014
• Bump version to 0.4.1-preview.1 by @jeffhandley in #1031

New Contributors

• @eduardomb-aw made their first contribution in #927
• @Youssef1313 made their first contribution in #958
• @ericstj made their first contribution in #994
• @halllo made their first contribution in #834
• @gewarren made their first contribution in #1024

Full Changelog: v0.4.0-preview.3...v0.4.1-preview.1

v0.4.0-preview.3

What's Changed

• Implement SEP-973: Icons and metadata support for Implementations, Resources, Tools, and Prompts by @Copilot in #802
• Fix slow shutdown when a Streamable HTTP client is connected by @halter73 in #843
• Fix sample projects to work in GitHub Codespaces by installing .NET 9.0 SDK by @Copilot in #854
• Fix markdown links in docs and add docfx CI validation by @Copilot in #862
• Remove problematic System.Net.Http package reference from tests by @stephentoub in #867
• Propagate tool call exceptions through filters by @halter73 in #844
• Fix comments on McpServerTool/Prompt/Resource by @stephentoub in #866
• Add net10.0 assets and run some fixers by @stephentoub in #875
• Fix: Synthesize handlers for empty tool/prompt/resource collections by @Copilot in #865
• Convert EverythingServer to use Streamable HTTP by @mikekistler in #709
• Add McpMetaAttribute for attaching metadata to tools, prompts, and resources by @Copilot in #857
• Add comprehensive test coverage for resource capability preservation with WithResources by @Copilot in #896
• Fix regression matching templated McpServerResources by @halter73 in #897
• Call Regex.IsMatch when Match is not needed by @halter73 in #903

Repository Infrastructure Updates

• ✨ Set up Copilot instructions for repository by @Copilot in #858
• Pin global.json to rc.1 SDK by @halter73 in #869
• Pin GitHub workflows to rc.1 SDK by @halter73 in #871
• Delete .github/workflows/copilot-setup-steps.yml by @stephentoub in #882
• Update copilot-setup-steps.yml to use global.json for .NET SDK version by @Copilot in #888
• Add copilot-setup-steps.yml to preinstall .NET 10 SDK in GitHub Copilot environment by @Copilot in #877
• Move copilot-setup-steps.yml to workflows directory per GitHub documentation by @Copilot in #879
• Add copilot setup steps by @stephentoub in #885
• Onboard repository to Dependabot for automated testing and AI dependency updates by @Copilot in #800
• Bump actions/setup-node from 4.3.0 to 5.0.0 by @dependabot[bot] in #845
• Bump actions/upload-pages-artifact from 3.0.1 to 4.0.0 by @dependabot[bot] in #848
• Bump danielpalme/ReportGenerator-GitHub-Action from 5.4.4 to 5.4.17 by @dependabot[bot] in #847
• Bump actions/setup-dotnet from 4.3.1 to 5.0.0 by @dependabot[bot] in #846
• Bump becheran/mlc from 0.21.0 to 1.0.0 by @dependabot[bot] in #852
• Bump actions/checkout from 4.2.2 to 5.0.0 by @dependabot[bot] in #851
• Bump actions/download-artifact from 4.2.1 to 5.0.0 by @dependabot[bot] in #849
• Bump the opentelemetry-testing group with 2 updates by @dependabot[bot] in #901
• Bump actions/setup-node from 5.0.0 to 6.0.0 by @dependabot[bot] in #900
• Update download-artifact path reference by @jeffhandley in #905

Full Changelog: v0.4.0-preview.2...v0.4.0-preview.3

v0.4.0-preview.2

Breaking Changes

The v0.4.0-preview.2 release includes a breaking change to the Streamable HTTP transport's Stateless mode. Because Stateless mode no longer uses a session ID nor relies on data protection, client information like the client's name and version are no longer tracked across requests meaning McpServer.ClientInfo will always be null. If you need ClientInfo in your handlers, we recommend using the default stateful mode.

What's Changed

• Bump version to 0.4.0-preview.2 by @jeffhandley in #818
• Onboard repo to the .NET 10 sdk by @eiriktsarpalis in #822
• Move options validation to constructor by @halter73 in #826
• Make "Stateless" mode sessionless by @halter73 in #760
• Update sample with URI validation by @localden in #824
• Fix support for sending server notifications with request-specific McpServer instances used outside their original scope. by @eiriktsarpalis in #832

Full Changelog: v0.4.0-preview.1...v0.4.0-preview.2

v0.4.0-preview.1

Breaking Changes

The v0.4.0-preview.1 release includes several breaking API changes, included in #723 and #765.

1. Interfaces were replaced by abstract classes to better allow evolution of the API surface in future versions.
2. Factory classes were deprecated and replaced by static factory methods to improve usability and align with existing .NET patterns such as HttpClient.
3. The 'Sse' (Server-Sent Events) APIs were renamed to use 'Http', aligning with the revised Transports nomenclature.
4. APIs for handlers and callbacks were decoupled from the protocol representation for improved separation of concerns.

Interfaces replaced by abstract classes

The IMcpClient, IMcpServer, and IMcpEndpoint interfaces are marked as [Obsolete] and will be removed in an upcoming release. These interfaces are replaced by new abstract classes.

Old	New
IMcpClient	McpClient
IMcpServer	McpServer
IMcpEndpoint	McpSession

Action: Replace usages of the obsolete interfaces with the new abstract types. Change variable, field, and parameter types. Optional, but recommended: rename identifiers like endpoint → session for clarity.

Factory classes deprecated

The McpClientFactory and McpServerFactory classes are marked as [Obsolete] and will be removed in an upcoming release.

Old	New
McpClientFactory.CreateAsync(...)	McpClient.CreateAsync(...)
McpServerFactory.CreateAsync(...)	McpServer.CreateAsync(...)

Action: Replace calls to the factory classes with the static factory methods on the abstract classes.

Rename SseClientTransport to HttpClientTransport

The SseClientTransport and SseClientTransportOptions classes were renamed to reflect Http naming instead of Sse.

Old	New
SseClientTransport	HttpClientTransport
SseClientTransportOptions	HttpClientTransportOptions

Action: Update usage of these types to utilize the new type names.

Decouple handlers and collections from protocol types

Handlers and collections in the Capabilities types are now obsolete; they've been moved to McpClientOptions and McpServerOptions.

Old	New
myClientOptions.Capabilities.NotificationHandlers	myClientOptions.Handlers.NotificationHandlers
myClientOptions.Capabilities.Elicitation.ElicitationHandler	myClientOptions.Handlers.ElicitationHandler
myClientOptions.Capabilities.Roots.RootsHandler	myClientOptions.Handlers.RootsHandler
myClientOptions.Capabilities.Sampling.SamplingHandler	myClientOptions.Handlers.SamplingHandler
myServerOptions.Capabilities.NotificationHandlers	myServerOptions.Handlers.NotificationHandlers
myServerOptions.Capabilities.Completions.CompleteHandler	myServerOptions.Handlers.CompleteHandler
myServerOptions.Capabilities.Logging.SetLoggingLevelHandler	myServerOptions.Handlers.SetLoggingLevelHandler
myServerOptions.Capabilities.Prompts.ListPromptsHandler	myServerOptions.Handlers.ListPromptsHandler
myServerOptions.Capabilities.Prompts.GetPromptHandler	myServerOptions.Handlers.GetPromptHandler
myServerOptions.Capabilities.Prompts.PromptCollection	myServerOptions.PromptCollection
myServerOptions.Capabilities.Resources.ListResourceTemplatesHandler	myServerOptions.Handlers.ListResourceTemplatesHandler
myServerOptions.Capabilities.Resources.ListResourcesHandler	myServerOptions.Handlers.ListResourcesHandler
myServerOptions.Capabilities.Resources.ReadResourceHandler	myServerOptions.Handlers.ReadResourceHandler
myServerOptions.Capabilities.Resources.SubscribeToResourcesHandler	myServerOptions.Handlers.SubscribeToResourcesHandler
myServerOptions.Capabilities.Resources.UnsubscribeFromResourcesHandler	myServerOptions.Handlers.UnsubscribeFromResourcesHandler
myServerOptions.Capabilities.Resources.ResourceCollection	myServerOptions.ResourceCollection
myServerOptions.Capabilities.Tools.ListToolsHandler	myServerOptions.Handlers.ListToolsHandler
myServerOptions.Capabilities.Tools.CallToolHandler	myServerOptions.Handlers.CallToolHandler
myServerOptions.Capabilities.Tools.ToolCollection	myServerOptions.ToolCollection

Action: Replace usages of the obsolete handlers and collections with the corresponding APIs on the options types.

Collections

Old

new McpServerOptions() 
{
    Capabilities = new() 
    {
        Tools = new() 
        { 
            ToolCollection = [McpServerTool.Create(...)] 
        }
    }
};

New

new McpServerOptions()
{
    ToolCollection = [McpServerTool.Create(...)]
};

Handlers

Old

new McpServerOptions()
{
    Capabilities = new()
    {
        Tools = new()
        {
            CallToolHandler = (request, ct) => { ... }
        }
    }
};

New

new McpServerOptions()
{
    Handlers = new()
    {
        CallToolHandler = (request, ct) => { ... }
    }
};

What's Changed

• Add articles on logging and progress by @mikekistler in #717
• Update packages and Infra by @eiriktsarpalis in #732
• Clarify default value in ElicitResult documentation by @timheuer in #731
• Add WithXx overloads that take target instance by @stephentoub in #706
• Improvements to dynamic client registration by @S-Luiten in #609
• Improved samples: added weather tool in AspNetCoreSseServer and option to connect via http to AspNetCoreSseServer. by @sabbadino in #469
• Convert ValueStringBuilder.cs to file-scoped namespaces by @Revazashvili in #746
• Include docs samples in solution build by @mikekistler in #751
• Fix typo in LoggingTools.cs by @ElanHasson in #740
• Per RouteValue Tools Sample by @PederHP in #724
• Add middleware and authz support for server-side handlers by @halter73 in #733
• Add ElicitAsync (#630) by @mehrandvd in #715
• Correct 'McpTool' to 'McpServerTool' in README by @asklar in #775
• Restructure IMcpEndpoint, IMcpClient, and IMcpServer by @MackinnonBuck in #723
• Add McpSession.NegotiatedProtocolVersion property. by @eiriktsarpalis in #794
• Update MEAI dependencies. by @eiriktsarpalis in #801
• Add conceptual docs on accessing HttpContext by @mikekistler in #771
• Decouple Handlers and Collections from protocol types by @jozkee in #765
• Add devcontainer.json to support .NET 9 samples in GitHub Codespaces by @Copilot in #779
• Fix stdio client transport CLI argument escaping. by @eiriktsarpalis in #811
• Bump M.E.AI version by @stephentoub in #817
• Bump to 0.4.0-preview.1 for releasing breaking changes by @jeffhandley in #813

New Contributors

• @sabbadino made their first contribution in #469
• @Revazashvili made their first contribution in #746
• @ElanHasson made their first contribution in #740
• @mehrandvd made their first contribution in #715
• @asklar made their first contribution in #775
• @MackinnonBuck made their first contribution in #723
• @jozkee made their first contribution in https://github.com/modelcontextprotocol/csharp-sd...

v0.3.0-preview.4

What's Changed

• Respect HandleResponse() and SkipHandler() calls in OnResourceMetadataRequest by @halter73 in #607
• UnreferenceDisposable made slimmer by @Scooletz in #627
• IdleTracking uses lists instead of SortedSet by @Scooletz in #629
• Fix ResourceLinkBlock deserialization by adding missing "name" case by @Copilot in #645
• Add an in-memory transport sample by @stephentoub in #664
• Remove 'Sse' from AspNetCoreSseServer sample name by @halter73 in #665
• Fix NotSupportedException when returning IEnumerable by @Copilot in #675
• Enhance HTTP and MCP session logging by @theojiang25 in #608
• Remove special-casing of string enumerables in McpServerTool by @stephentoub in #699
• Prune idle sessions before starting new ones by @halter73 in #701
• Add framework for conceptual docs by @mikekistler in #708

New Contributors

• @Scooletz made their first contribution in #627
• @Copilot made their first contribution in #645
• @theojiang25 made their first contribution in #608

Full Changelog: v0.3.0-preview.3...v0.3.0-preview.4

v0.3.0-preview.3

What's Changed

• Enable netfx testing. by @eiriktsarpalis in #588
• fix: Prevent crash when Options.ResourceMetadata is null but handled by event by @DavidParks8 in #603
• Update to M.E.AI 9.7.0 by @stephentoub in #602
• Ensure IsExternalInit is type forwarded on NET builds by @stephentoub in #619
• Flow ExecutionContext with JsonRpcMessage by @halter73 in #616
• Update MEAI version and add regression test for #601. by @eiriktsarpalis in #628

New Contributors

• @DavidParks8 made their first contribution in #603

Full Changelog: v0.3.0-preview.2...v0.3.0-preview.3

v0.3.0-preview.2

What's Changed

• Authorization Support (Using ASP.NET Core Native AuthN/AuthZ Integration) by @localden in #377
• Fix URI template derivation and lookup by @eiriktsarpalis in #530
• Implement ReturnJsonSchema in McpClientTool. by @S-Luiten in #538
• Document default value for UseStructuredContent. by @S-Luiten in #539
• Fix deserialization of PrimitiveSchemaDefinition by @stephentoub in #537
• Update README.md to fix the server sample build issue. by @Anduin2017 in #546
• Styling: remove a few redundant parens from object initializer expressions. by @eiriktsarpalis in #548
• Delete unused method and linker suppression by @stephentoub in #567
• Enable injecting IMcpServer and friends into ctors by @stephentoub in #570
• Removed space by @rokenbuzz in #563
• Make CallToolResult.IsError optional by @stephentoub in #573
• Fix relative path resolution in sample app. by @eiriktsarpalis in #572
• Add CallToolResult.ToChatMessage extension method by @stephentoub in #575
• Change default name casing of McpServerXx.Create tools/prompts by @stephentoub in #568
• Fixed StreamableHttpClientSessionTransport.cs for netstandard by @lucapivato in #582

New Contributors

• @S-Luiten made their first contribution in #538
• @Anduin2017 made their first contribution in #546
• @rokenbuzz made their first contribution in #563
• @lucapivato made their first contribution in #582

Full Changelog: v0.3.0-preview.1...v0.3.0-preview.2

v0.3.0-preview.1

What's Changed

• Remove incorrect acknowledgement from README of new Core package by @halter73 in #482
• Add context to complete requests by @stephentoub in #488
• Add structured output/output schema support for server-side tools. by @eiriktsarpalis in #480
• Pass session id's to MCP endpoints. by @eiriktsarpalis in #466
• Make enums serialize as strings if using the reflection-based serializer. by @eiriktsarpalis in #473
• Update Microsoft.Extensions.AI version & expose JSON configuration on McpServerResourceCreateOptions by @sbomer in #511
• Update content according to latest spec by @stephentoub in #513
• Fix visibility of polyfill by @stephentoub in #523
• Add a callback for receiving stderr output by @stephentoub in #525
• Send MCP-Protocol-Version header in Streamable HTTP client transport by @halter73 in #500
• Send DELETE request when closing a Streamable HTTP session on the client by @halter73 in #501
• Fix QuickstartClient path by @stephentoub in #528
• Add 2025-06-18 as supported version by @stephentoub in #529
• Bump version number to 0.3.0 by @eiriktsarpalis in #534

New Contributors

• @sbomer made their first contribution in #511

Full Changelog: v0.2.0-preview.3...v0.3.0-preview.1

v0.2.0-preview.3

What's Changed

• Bump version to 0.2.0-preview.3 by @jeffhandley in #465
• Add elicitation capability by @stephentoub in #467
• Convert records to classes by @eiriktsarpalis in #470
• Convert solution to slnx by @eiriktsarpalis in #472
• Update dependency versions by @stephentoub in #474
• Add ModelContextProtocol.Core package by @halter73 in #428
• Improve protocol version handling by @stephentoub in #468
• Don't conflate request and response IDs in Streamable HTTP transports by @halter73 in #475

Full Changelog: v0.2.0-preview.2...v0.2.0-preview.3

v0.2.0-preview.2

What's Changed

• Bump version to 0.2.0-preview.2 by @jeffhandley in #424
• Serilog AOT has been fixed as of 4.3.0 by @agocke in #434
• Allow more accept headers by @halter73 in #429
• Update README.md by @Gavinluo in #437
• SSE client transport: tolerate return of RPC responses in POST requests. by @eiriktsarpalis in #445
• Log tool invocation errors by @kooshi in #447
• Automatically fall back from Streamable HTTP to SSE on the client by default by @halter73 in #456
• Set CreateNoWindow=true in RunProcessAndWaitForExit by @stephentoub in #462
• Update documentation of McpJsonUtilities.DefaultOptions. by @eiriktsarpalis in #463

New Contributors

• @Gavinluo made their first contribution in #437
• @kooshi made their first contribution in #447

Full Changelog: 0.2.0-preview.1...v0.2.0-preview.2