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

Documentation Updates

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

Repository Infrastructure Updates

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

New Contributors

• @eduardomb-aw made their first contribution in https://github.com/modelcontextprotocol/csharp-sdk/pull/927
• @Youssef1313 made their first contribution in https://github.com/modelcontextprotocol/csharp-sdk/pull/958
• @ericstj made their first contribution in https://github.com/modelcontextprotocol/csharp-sdk/pull/994
• @halllo made their first contribution in https://github.com/modelcontextprotocol/csharp-sdk/pull/834
• @gewarren made their first contribution in https://github.com/modelcontextprotocol/csharp-sdk/pull/1024

Full Changelog: https://github.com/modelcontextprotocol/csharp-sdk/compare/v0.4.0-preview.3...v0.4.1-preview.1