This is the first stable release of the ModelContextProtocol C# SDK. Thank you to all of the contributors who helped us achieve this milestone!

Breaking Changes

Refer to the C# SDK Versioning documentation for details on versioning and breaking change policies.

1. Mark RunSessionHandler experimental (MCPEXP002) #1383
   • HttpServerTransportOptions.RunSessionHandler is now annotated with [Experimental("MCPEXP002")]
   • Code that references RunSessionHandler will produce a compile-time warning (or error with TreatWarningsAsErrors); suppress with #pragma warning disable MCPEXP002
   • Consider using ConfigureSessionOptions as an alternative; RunSessionHandler may be removed or change signatures in a future release

What's Changed

• Add 2025-03-26 OAuth backward compatibility for client conformance #1374 by @jeffhandley (co-authored by @Copilot)
• Mark RunSessionHandler experimental (MCPEXP002) #1383 by @halter73 (co-authored by @Copilot @jeffhandley)

Documentation Updates

• Fix a few bugs in the docs #1379 by @stephentoub
• Add and augment conceptual docs #1375 by @jeffhandley (co-authored by @Copilot @mikekistler @stephentoub @halter73)

Repository Infrastructure Updates

• Bump to version 1.0.0 (stable) #1384 by @jeffhandley

Acknowledgements

• @halter73 @stephentoub @mikekistler @eiriktsarpalis reviewed pull requests

Full Changelog: v1.0.0-rc.1...v1.0.0

This release candidate completes a full API surface area audit ahead of the 1.0.0 stable release, with more changes to public APIs to ensure consistency and long-term maintainability. Protocol DTO types are updated to match the MCP specification, deprecated filter APIs are removed, and bug fixes improve transport reliability and JSON handling.

Breaking Changes

Refer to the C# SDK Versioning documentation for details on versioning and breaking change policies.

1. Address asymmetry in McpServerHandlers/McpClientHandlers and make all filter properties settable #1337

   • Seals McpClientHandlers to match the already-sealed McpServerHandlers
   • Makes McpServerOptions.Handlers, McpServerOptions.Filters, and all IList<T> filter properties settable with null validation

2. Remove server back-references from protocol DTO types #1345

   • Removes Tool.McpServerTool, Prompt.McpServerPrompt, Resource.McpServerResource, and ResourceTemplate.McpServerResource properties
   • Use McpServerPrimitiveCollection.TryGetPrimitive() for name-based lookups instead

3. Make Tool.Name required to match other protocol types #1351

   • Adds required modifier to Tool.Name, matching Prompt.Name, Resource.Name, and other IBaseMetadata implementations
   • Callers must now specify Name in object initializers

4. Make LoggingMessageNotificationParams.Data required per MCP spec #1353

   • Changes LoggingMessageNotificationParams.Data from JsonElement? to required JsonElement per the MCP specification

5. Fix CreateMessageRequestParams.Metadata type to JsonObject #1354

   • Changes CreateMessageRequestParams.Metadata from JsonElement? to JsonObject? to match all other _meta/Meta properties in the SDK

6. Normalize CallToolResult.StructuredContent to JsonElement? #1357

   • Changes CallToolResult.StructuredContent from JsonNode? to JsonElement? for consistency with the rest of the SDK
   • Use JsonSerializer.SerializeToElement() to produce a JsonElement

7. Unify service configuration for ISseEventStreamStore, IMcpTaskStore, and ISessionMigrationHandler #1362

   • Consistent options + DI pattern: explicit options property > DI resolution

8. Add explicit [Experimental] protected constructors to McpClient and McpServer #1363

   • Protected constructors on McpClient and McpServer now require suppressing MCPEXP002 to subclass

9. Remove MCP9002 obsolete APIs and document obsolete diagnostics #1366

   • Removes the 13 AddXxxFilter extension methods on IMcpServerBuilder (e.g. AddCallToolFilter, AddListToolsFilter) that were deprecated under diagnostic MCP9002
   • Use WithRequestFilters() and WithMessageFilters() instead

10. Fix McpClientPrompt/Resource types to use RequestOptions like McpClientTool does #1370

    • Replaces JsonSerializerOptions with RequestOptions parameter for consistency across McpClientPrompt, McpClientResource, and McpClientTool

What's Changed

• Make Tool.Name required to match other protocol types #1351 by @stephentoub (co-authored by @Copilot)
• Make LoggingMessageNotificationParams.Data required per MCP spec #1353 by @stephentoub (co-authored by @Copilot)
• Fix off-by-one error in reconnection attempts #1356 by @stephentoub (co-authored by @Copilot)
• Remove server back-references from protocol DTO types #1345 by @stephentoub (co-authored by @Copilot)
• Fix base64 deserialization when JSON encoder escapes forward slashes #1342 by @stephentoub (co-authored by @Copilot)
• Increase MaxReconnectionAttempts default from 2 to 5 #1355 by @stephentoub (co-authored by @Copilot)
• Prevent cancellation of initialize request per MCP spec #1350 by @stephentoub (co-authored by @Copilot)
• Address asymmetry in McpServerHandlers/McpClientHandlers and make all filter properties settable #1337 by @stephentoub (co-authored by @Copilot)
• Normalize CallToolResult.StructuredContent to JsonElement? #1357 by @stephentoub (co-authored by @Copilot)
• Fix CreateMessageRequestParams.Metadata type to JsonObject #1354 by @stephentoub (co-authored by @Copilot)
• Remove MCP9002 obsolete APIs and document obsolete diagnostics #1366 by @jeffhandley (co-authored by @Copilot)
• Add explicit [Experimental] protected constructors to McpClient and McpServer #1363 by @stephentoub (co-authored by @Copilot @jeffhandley)
• Fix McpClientPrompt/Resource types to use RequestOptions like McpClientTool does #1370 by @stephentoub (co-authored by @Copilot)
• Unify service configuration for ISseEventStreamStore, IMcpTaskStore, and ISessionMigrationHandler #1362 by @MackinnonBuck

Documentation Updates

• Fix malformed XML doc on McpServerPrimitiveCollection.Contains #1348 by @stephentoub (co-authored by @Copilot)
• Clarify null semantics in ToolAnnotations hint property docs #1346 by @stephentoub (co-authored by @Copilot)
• Fix compilation errors in README code samples #1369 by @jeffhandley
• Fix XML documentation spelling, grammar, and correctness issues across SDK #1372 by @stephentoub (co-authored by @Copilot)
• Add Roadmap document and navigation link #1373 by @jeffhandley

Test Improvements

• Add CloneResourceMetadataClonesAllProperties test using public reflection #1343 by @stephentoub (co-authored by @Copilot)

Repository Infrastructure Updates

• Bump version to 1.0.0-rc.1 #1376 by @jeffhandley
• Add README code sample validation step to release-notes skill #1371 by @jeffhandley
• Bump the other-testing group with 1 update #1358
• Bump Anthropic from 12.5.0 to 12.8.0 #1359

Acknowledgements

• @monikbhatt submitted issue #1340 (resolved by #1342)
• @gabaoalb submitted issue #1331 (resolved by #1337)
• @halter73 @MackinnonBuck @ericstj reviewed pull requests

Full Changelog: v0.9.0-preview.2...v1.0.0-rc.1

This release focuses on API surface consistency and correctness ahead of 1.0.0. Public collection properties are now typed as IList<T> instead of concrete List<T> or T[], and Root.Meta is aligned with the rest of the protocol DTOs by using JsonObject?. Other improvements include new experimental Extensions support for capabilities, missing ResourceLinkBlock properties, improved mimeType handling, and several documentation and test reliability fixes.

We plan to release the stable 1.0.0 release early in the week of February 23, 2026.

Breaking Changes

Refer to the C# SDK Versioning documentation for details on versioning and breaking change policies.

1. Replace concrete collection types with interfaces in public API surface #1326

   • List<T> and T[] properties on ProtectedResourceMetadata, ToolResultContentBlock, ListTasksResult, and DynamicClientRegistrationResponse changed to IList<T>. Replace .Length with .Count and cast to List<T> if List<T>-specific members are needed.

2. Fix Root.Meta to use JsonObject instead of JsonElement #1341

   • Root.Meta changed from JsonElement? to JsonObject?. Replace meta.Value.GetProperty("key").GetString() with (string?)meta["key"].

3. Make UrlElicitationRequiredErrorData.Elicitations consistent with other Protocol DTOs #1335

   • Elicitations changed from IReadOnlyList<ElicitRequestParams> with init to IList<ElicitRequestParams> with set. Code using List<T> is unaffected since it implements both interfaces.

What's Changed

• Remove dead code: options ??= new() in McpServerImpl constructor #1322 by @stephentoub (co-authored by @Copilot)
• Remove unnecessary _connectCts field from McpClientImpl #1323 by @stephentoub (co-authored by @Copilot)
• Add missing Title and Icons properties to ResourceLinkBlock #1320 by @stephentoub (co-authored by @Copilot)
• Omit null mimeType from ResourceContents JSON serialization #1325 by @stephentoub (co-authored by @Copilot)
• Validate mimeType in ImageContentBlock.FromBytes and AudioContentBlock.FromBytes #1321 by @stephentoub (co-authored by @Copilot)
• Replace concrete collection types with interfaces in public API surface #1326 by @stephentoub (co-authored by @Copilot)
• Make UrlElicitationRequiredErrorData.Elicitations consistent with other Protocol DTOs #1335 by @stephentoub (co-authored by @Copilot)
• Fix Metadata delegation in DelegatingMcpServerTool/Prompt/Resource #1338 by @stephentoub (co-authored by @Copilot @jeffhandley)
• Add Extensions support to ClientCapabilities and ServerCapabilities #1317 by @stephentoub (co-authored by @Copilot)
• Fix _meta properties to use JsonObject #1341 by @stephentoub (co-authored by @Copilot)

Documentation Updates

• Fix incorrect XML doc comments in McpClient.Methods.cs #1333 by @stephentoub (co-authored by @Copilot)
• Add missing exception documentation for public APIs #1339 by @stephentoub (co-authored by @Copilot)

Test Improvements

• Fix flaky DiagnosticTests on net10.0 by waiting for specific activities #1324 by @stephentoub (co-authored by @Copilot)
• Fix flaky sse-retry conformance test due to CI timing overhead #1336 by @ericstj (co-authored by @Copilot)

Repository Infrastructure Updates

• Bump version to 1.0.0-rc.1 #1327 by @jeffhandley (co-authored by @Copilot)
• Add release-notes, breaking-changes, and bump-version Copilot skills #1328 by @jeffhandley (co-authored by @Copilot)
• Bump hono from 4.11.7 to 4.12.0 in the npm_and_yarn group across 1 directory #1316
• Bump version down to 0.9.0-preview.2 since we are still changing APIs #1344 by @jeffhandley (co-authored by @Copilot)

Acknowledgements

• @halter73 @eiriktsarpalis @mikekistler reviewed pull requests

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

The 0.9.0-preview.1 release includes multiple breaking changes focused on quality, extensibility, usability, and API consistency as we continue refining the SDK in preparation for a stable 1.0.0 release.

We plan to release the stable 1.0.0 release early in the week of February 23, 2026.

Breaking Changes

Refer to the C# SDK Versioning documentation for details on versioning and breaking change policies.

1. Use ReadOnlyMemory<byte> for binary data to eliminate UTF-16 transcoding #1070

   • ImageContentBlock.Data, AudioContentBlock.Data, and BlobResourceContents.Blob changed from string to ReadOnlyMemory<byte>; FromImage/FromAudio renamed to FromBytes; BlobResourceContents.Data renamed to DecodedData
   • Migration: Use DecodedData for decoded bytes and FromBytes(...) factory methods

2. Split configuration of request and message filters #1308

   • Add*Filter extension methods on IMcpServerBuilder replaced by WithMessageFilters and WithRequestFilters callbacks with grouped builder instances
   • Migration: Wrap existing filter registration inside the new callback methods

3. Don't treat McpServerHandlers as an independent options type #1313

   • McpServerHandlers no longer resolved via IOptions<McpServerHandlers>; handlers set directly on McpServerOptions.Handlers
   • Migration: Configure handlers through McpServerOptions directly

4. Add ISessionMigrationHandler #1270

   • Stateful Streamable HTTP POST requests without a session ID are now rejected with 400 unless the message is an initialize request
   • Compat switch: ModelContextProtocol.AspNetCore.AllowNewSessionForNonInitializeRequests = true restores previous behavior

5. Change ProtectedResourceMetadata URI properties to strings #1264

   • Multiple properties changed from Uri?/List<Uri> to string?/List<string> to avoid unwanted URI normalization
   • Migration: Use string values directly instead of Uri objects

6. Hide experimental types from external source generators using internal property pattern #1301

   • Experimental properties now use [JsonIgnore] + internal delegate pattern; external source generators no longer reference experimental types
   • No code changes needed for most consumers

7. Validate MCP-Protocol-Version header in Streamable HTTP handler #1277

   • Server returns HTTP 400 for invalid/unsupported header values; missing header still allowed
   • Migration: Ensure clients send a valid protocol version or omit the header

8. Update McpErrorCode and fix error code usage to align with MCP spec #1291

   • Task support validation errors changed from MethodNotFound to InvalidParams
   • Migration: Update error code checks for task support validation scenarios

What's Changed

• Bring up to 0.1.13 conformance #1254 by @stephentoub
• Change ProtectedResourceMetadata URI properties to strings and build resource strings directly #1264 by @halter73 (co-authored by @Copilot)
• Log tool call name on success, not just failure #1256 by @halter73 (co-authored by @Copilot)
• Fix HttpClient timeout for long-running tools without event stream store #1268 by @halter73 (co-authored by @Copilot)
• Fix stderr event loss due to missing WaitForExit in DisposeProcess #1280 by @stephentoub (co-authored by @Copilot)
• Update McpErrorCode XML docs and fix error code usage to align with MCP spec #1291 by @stephentoub (co-authored by @Copilot)
• Add X-Accel-Buffering header to SSE responses #1294 by @stephentoub (co-authored by @Copilot)
• Fix StdioServerTransport.DisposeAsync() hang: CancellableStdinStream missing Dispose override #1276 by @stephentoub (co-authored by @Copilot)
• Avoid intermediate strings in MCP transport serialization #1274 by @stephentoub (co-authored by @Copilot @halter73)
• Validate MCP-Protocol-Version header in Streamable HTTP handler #1277 by @stephentoub (co-authored by @Copilot)
• Hide experimental types from external source generators using internal property pattern #1301 by @MackinnonBuck
• Use ReadOnlyMemory<byte> for binary data to eliminate UTF-16 transcoding #1070 by @stephentoub (co-authored by @Copilot @ericstj)
• Add ISessionMigrationHandler #1270 by @MackinnonBuck
• Don't treat McpServerHandlers as an independent options type #1313 by @halter73
• Split configuration of request and message filters #1308 by @halter73 (co-authored by @Copilot)

Documentation Updates

• Align InitializeResult.instructions XML docs with latest MCP spec guidance #1290 by @stephentoub (co-authored by @Copilot @halter73)
• Align sampling specification XML docs with spec revision d165cd6 #1293 by @stephentoub (co-authored by @Copilot)
• Clarify request-scoped tool semantics in CreateMessageRequestParams #1295 by @stephentoub (co-authored by @Copilot)
• Document https:// direct-fetch provision in ReadResourceRequestParams #1296 by @stephentoub (co-authored by @Copilot)
• Add validation and error signaling guidance to MCP tool XML docs #1275 by @stephentoub (co-authored by @Copilot)
• Update SECURITY.md to use GitHub Security Advisories #1306 by @localden
• Add docs for working with experimental APIs #1307 by @MackinnonBuck (co-authored by @jeffhandley)

Test Improvements

• Use package-lock.json to pin conformance test dependencies #1247 by @halter73
• Update to MCP conformance tests version 0.1.13 #1249 by @stephentoub
• Add AOT compatibility publish test #1246 by @stephentoub (co-authored by @Copilot @eiriktsarpalis)
• Add tests to verify McpClient.DisposeAsync doesn't hang #1252 by @halter73
• Add auth regression test for missing resource in PRM #1265 by @halter73 (co-authored by @Copilot)
• Fix test for CannotAuthenticate when metadata is missing #1266 by @halter73 (co-authored by @Copilot)
• Fix flaky stderr test: call WaitForExit() after WaitForExitAsync() to flush ErrorDataReceived events #1278 by @stephentoub (co-authored by @Copilot)
• Unskip GetRequest_Receives_UnsolicitedNotifications test #1286 by @mikekistler (co-authored by @Copilot)
• Fix flaky sse-retry conformance test caused by CI timing sensitivity #1279 by @stephentoub (co-authored by @Copilot)
• Add serialization roundtrip tests for all Protocol namespace types #1289 by @stephentoub (co-authored by @Copilot)
• Update tests for @modelcontextprotocol/server-everything 2026.1.26 #1273 by @stephentoub (co-authored by @Copilot)
• Reduce flakiness in long-running stateless HTTP tool timeout test #1300 by @halter73 (co-authored by @Copilot)
• Use TimeProvider in InMemoryMcpTaskStore for deterministic testing #1303 by @halter73 (co-authored by @Copilot)

Repository Infrastructure Updates

• Bump version to 0.9.0-preview.1 #1245 by @jeffhandley (co-authored by @halter73)
• Bump qs from 6.14.1 to 6.14.2 in the npm_and_yarn group across 1 directory #1271
• Bump the other-testing group with 2 updates #1283
• Bump Anthropic from 12.3.0 to 12.5.0 #1284
• Bump Microsoft.Extensions.AI from 10.2.0 to 10.3.0 #1285
• Bump the serilog-testing group with 1 update #1282
• Bump the testing-frameworks group with 1 update #1281
• Bump ajv from 8.17.1 to 8.18.0 in the npm_and_yarn group across 1 directory #1302

Acknowledgements

• @FICTURE7 submitted issue #1122 (resolved by #1264)
• @delepster submitted issue #1155 (resolved by #1270)
• @KenBrannigan submitted issue #696 (resolved by #1275)
• @333fred @eerhardt reviewed pull requests

Full Changelog: v0.8.0-preview.1...v0.9.0-preview.1

The 0.8.0-preview.1 release includes new server-side capabilities including message-level filters and a distributed cache-backed event stream store, along with several bug fixes for transport reliability. This release also includes a breaking change that seals public Protocol reference types to prevent external inheritance, reinforcing the SDK's API contract as we continue refining toward a stable 1.0.0 release.

Breaking Changes

Refer to the C# SDK Versioning documentation for details on versioning and breaking change policies.

1. Seal public Protocol reference types to prevent external inheritance #1232
   • Several public classes sealed: JsonRpcMessageContext, ElicitRequestParams.RequestSchema, ElicitRequestParams.LegacyTitledEnumSchema, ContentBlock.Converter, ResourceContents.Converter, PrimitiveSchemaDefinition.Converter
   • ElicitRequestParams.EnumSchema removed; use LegacyTitledEnumSchema directly
   • Migration: Remove any inheritance from these types; replace EnumSchema references with LegacyTitledEnumSchema

What's Changed

• Add Trace-level logging for JSON-RPC payloads in transports #1191 by @stephentoub (co-authored by @halter73 @Copilot)
• Use Process.Kill(entireProcessTree: true) on .NET for faster process termination #1187 by @stephentoub
• Include response body in HttpRequestException for transport client errors #1193 by @stephentoub (co-authored by @Copilot)
• Fix race condition in SSE GET request initialization #1212 by @stephentoub
• Fix keyset pagination with monotonic UUIDv7-like task IDs #1215 by @eiriktsarpalis (co-authored by @stephentoub @Copilot)
• Add ILoggerFactory to StreamableHttpServerTransport #1213 by @stephentoub (co-authored by @Copilot)
• Add support for message-level filters to McpServer #1207 by @halter73
• Seal public Protocol reference types to prevent external inheritance #1232 by @stephentoub (co-authored by @Copilot)
• Add DistributedCacheEventStreamStore #1136 by @MackinnonBuck (co-authored by @halter73)

Documentation Updates

• Fix typo in elicitation.md #1186 by @ruyut
• Fix typo in progress.md #1189 by @ruyut
• Clarify McpMetaAttribute documentation scope #1242 by @stephentoub (co-authored by @Copilot)

Test Improvements

• Remove 10 second wait from docker tests #1188 by @stephentoub
• Fix Session_TracksActivities test #1200 by @stephentoub
• Fix StdioServerTransportTests to use Debug logging level instead of Trace #1209 by @stephentoub (co-authored by @Copilot)
• Centralize test timeout constants to fix sporadic CI failures #1210 by @ericstj (co-authored by @Copilot)
• Fix race condition in AutomaticInputRequiredStatusTests polling logic #1223 by @ericstj (co-authored by @stephentoub @Copilot)
• Centralize test timeout constants to fix CI flakiness #1224 by @ericstj (co-authored by @Copilot)
• Add test coverage for AdditionalHeaders in Streamable HTTP transport #1218 by @stephentoub (co-authored by @Copilot)
• Fix XunitLoggerProvider crash when background work logs after test disposal #1229 by @stephentoub (co-authored by @Copilot)
• Skip .NET Framework tests on non-Windows platforms #1226 by @stephentoub (co-authored by @Copilot)
• Suppress TimeProvider.Testing net472 warning #1227 by @stephentoub (co-authored by @Copilot)

Repository Infrastructure Updates

• Bump version to 0.8.0-preview.1 #1181 by @jeffhandley (co-authored by @Copilot)
• Bump actions/checkout from 6.0.1 to 6.0.2 #1173
• Bump the opentelemetry-testing group with 6 updates #1174
• Bump the other-testing group with 1 update #1233
• Bump Anthropic from 12.2.0 to 12.3.0 #1234

Acknowledgements

• @ruyut made their first contribution in #1186
• @scutuatua-crypto reviewed pull requests

Full Changelog: v0.7.0-preview.1...v0.8.0-preview.1

The 0.7.0-preview.1 release adds MCP task support, Streamable HTTP resumability with SSE event stream storage, and support for the 2025-11-25 protocol version. This release also introduces user-defined JsonSerializerOptions throughout SDK serialization APIs and includes several bug fixes for elicitation, source generator diagnostics, and URI template matching. The Streamable HTTP transport includes breaking changes to StreamableHttpServerTransport as part of the resumability implementation.

Breaking Changes

Refer to the C# SDK Versioning documentation for details on versioning and breaking change policies.

1. Streamable HTTP resumability + redelivery + SSE polling via server-side disconnect #1077
   • StreamableHttpServerTransport.OnInitRequestReceived property removed; replaced by EventStreamStore for resumability support
   • StreamableHttpServerTransport.SessionId setter changed from { get; set; } to { get; init; }
   • Migration: Remove OnInitRequestReceived usage; use ISseEventStreamStore via EventStreamStore for resumability. Set SessionId in the object initializer instead of post-construction assignment.

What's Changed

• Update licensing to Apache 2.0 for new contributions #1140 by @domdomegg
• Add 2025-11-25 as supported version #1130 by @stephentoub (co-authored by @Copilot)
• Streamable HTTP resumability + redelivery + SSE polling via server-side disconnect #1077 by @MackinnonBuck (co-authored by @halter73)
• Fix source generator diagnostic locations for incremental caching #1153 by @stephentoub (co-authored by @Copilot)
• Fix form mode elicitation schema check to apply for all form requests #1151 by @stephentoub (co-authored by @Copilot)
• Add support for user-defined JsonSerializerOptions throughout SDK serialization APIs #1113 by @stephentoub (co-authored by @Copilot @eiriktsarpalis)
• Fix reserved expansion (e.g. {+var}) when matching resources #1142 by @halter73
• Implement MCP task support #1170 by @eiriktsarpalis (co-authored by @halter73)

Documentation Updates

• Document MCP Server project template in README #1148 by @leslierichardson95 (co-authored by @mikekistler @jeffhandley)

Test Improvements

• Add comprehensive edge case tests for JSON-RPC payload shapes #1143 by @stephentoub (co-authored by @Copilot)
• Fix flaky test: Client_CanResumePostResponseStream_AfterDisconnection #1179 by @MackinnonBuck

Repository Infrastructure Updates

• Bump version to 0.7.0-preview.1 #1144 by @jeffhandley
• Bump actions/setup-dotnet from 5.0.1 to 5.1.0 #1157
• Bump actions/setup-node from 6.1.0 to 6.2.0 #1158
• Bump the testing-frameworks group with 1 update #1159
• Bump the other-testing group with 1 update #1160
• Update Microsoft.Extensions.AI to 10.2.0 #1165 by @eiriktsarpalis (co-authored by @Copilot @stephentoub)
• Update Anthropic SDK to 12.2.0 #1164 by @eiriktsarpalis (co-authored by @Copilot)
• Pin the MCP conformance tester package #1176 by @eiriktsarpalis

Acknowledgements

• @domdomegg made their first contribution in #1140
• @leslierichardson95 made their first contribution in #1148
• @mikekistler submitted #510 #1020 (resolved by #1077), #1129 (resolved by #1130), #943 (resolved by #1170)
• @halter73 @stephentoub @eiriktsarpalis @jeffhandley @mikekistler @MackinnonBuck @heaths @scutuatua-crypto reviewed pull requests

Full Changelog: v0.6.0-preview.1...v0.7.0-preview.1

This release includes improvements to source generator robustness, JSON-RPC deserialization performance, and OpenTelemetry semantic convention alignment. It also adds OAuth incremental scope consent support, fixes session timeout issues, and corrects tool result message handling for sampling with tools. Several documentation improvements and new client conformance tests round out the release.

What's Changed

• Remove s_additionalProperties from McpClientTool #1080 by @stephentoub (co-authored by @Copilot)
• Migrate from Anthropic.SDK to official Anthropic package #1083 by @stephentoub (co-authored by @Copilot)
• Improve caching in XmlToDescriptionGenerator #1010 by @stephentoub
• Support incremental scope consent (SEP-835) #1084 by @halter73
• Resource subscribe should be true if handler provided #676 by @PederHP (co-authored by @halter73 @mikekistler)
• Add request duration to LogRequestHandlerCompleted and LogRequestHandlerException log messages #1092 by @stephentoub (co-authored by @Copilot)
• Fix session timeout due to timestamp frequency mismatch and activity tracking #1106 by @stephentoub (co-authored by @Copilot @eiriktsarpalis)
• Add CS1066 suppressor for MCP server methods with optional parameters #1110 by @stephentoub (co-authored by @Copilot)
• Fix CreateSamplingHandler to use ChatRole.Tool for tool result messages #1128 by @stephentoub (co-authored by @Copilot @MackinnonBuck)
• Add examples of icons on tools, resources, prompts, and server implementation to EverythingServer #1096 by @mikekistler (co-authored by @halter73)
• Use fully-qualified type names in generated partial method signatures #1135 by @stephentoub (co-authored by @Copilot)
• Optimize JsonRpcMessage deserialization with single-pass parsing #1138 by @eiriktsarpalis (co-authored by @Copilot @Scooletz @stephentoub)
• Align telemetry with OpenTelemetry MCP semantic conventions #1139 by @stephentoub (co-authored by @Copilot)

Documentation Updates

• Fix Icon.Theme documentation to match MCP specification #1090 by @stephentoub (co-authored by @Copilot)
• Document HttpRequestException thrown by McpClient.CreateAsync #1095 by @stephentoub (co-authored by @Copilot)
• Add missing exception documentation to public API surface #1103 by @stephentoub (co-authored by @Copilot)
• Improve docs landing page #1114 by @gewarren
• Add CONTRIBUTING.md #1125 by @mikekistler

Test Improvements

• Remove private reflection from tests #1107 by @stephentoub (co-authored by @Copilot @halter73)
• Add client conformance tests #1102 by @mikekistler (co-authored by @halter73)

Repository Infrastructure Updates

• Bump actions/setup-node from 6.0.0 to 6.1.0 #1074
• Bump danielpalme/ReportGenerator-GitHub-Action from 5.5.0 to 5.5.1 #1073
• Bump actions/checkout from 5.0.1 to 6.0.0 #1005
• Bump version to 0.5.0-preview.2. Update NuGet Project URL. #1078 by @jeffhandley
• Update Microsoft.Extensions.AI dependencies to 10.1.0 #1082 by @stephentoub (co-authored by @Copilot)
• Update Microsoft.Extensions.AI* packages to latest versions #1093 by @stephentoub (co-authored by @Copilot)
• Bump actions/checkout from 6.0.0 to 6.0.1 #1100
• Bump becheran/mlc from 1.0.0 to 1.2.0 #1098
• Bump actions/upload-artifact from 5.0.0 to 6.0.0 #1099
• Bump actions/download-artifact from 6.0.0 to 7.0.0 #1097
• Bump the other-testing group with 1 update #1101
• Bump Anthropic from 11.0.0 to 12.0.1 #1118
• Bump the other-testing group with 1 update #1124
• Install mono in dev container #1133 by @mikekistler
• Bump Anthropic from 12.0.1 to 12.1.0 #1137
• Bump version to 0.6.0-preview.1 #1141 by @jeffhandley

Acknowledgements

• @333fred @Sergio0694 @Youssef1313 @scutuatua-crypto @tarekgh reviewed pull requests

Full Changelog: v0.5.0-preview.1...v0.6.0-preview.1

The 0.5.0-preview.1 release of the Model Context Protocol C# SDK introduces significant API improvements including a unified RequestOptions parameter bag for client methods, removal of previously obsoleted APIs, and new support for Client ID Metadata Documents and URL mode elicitation. This release also adds conformance tests, DebuggerDisplay attributes for protocol types, and a convenience overload for resource subscriptions with handler delegates.

Breaking Changes

The 0.5.0-preview.1 release includes several categories of breaking changes as we continue to refine the API surface area for the path toward a 1.0.0 stable release. Refer to the C# SDK Versioning documentation for information regarding our versioning, breaking change, and support approaches.

1. Add request options bag to high level requests and include Meta #970
   • High-level request methods refactored to use options bag. Methods CallToolAsync, GetPromptAsync, ListResourcesAsync, ReadResourceAsync, SubscribeResourceAsync, UnsubscribeResourceAsync, ListToolsAsync, ListPromptsAsync, and similar now accept a new RequestOptions parameter instead of individual JsonSerializerOptions and ProgressToken parameters.
   • Code that passes JsonSerializerOptions or ProgressToken as named or positional parameters to high-level request methods will break and must be updated to use the RequestOptions bag instead.
2. Remove obsolete APIs from codebase #985
   • McpServerFactory class: Removed obsolete factory class for creating MCP servers.
   • McpClientFactory class: Removed obsolete factory class for creating MCP clients.
   • Obsolete interfaces removed: IMcpEndpoint, IMcpClient, IMcpServer
   • Extension methods and properties that were previously marked obsolete are no longer available.
   • LegacyTitledEnumSchema and EnumSchema remain in place as obsolete APIs, but they now use a custom diagnostic ID of MCP9001 instead of the default CS0618 obsoletion diagnostic ID. This allows references to these APIs to be suppressed with a targeted diagnostic.
3. Fall back to well-known URL in client if 401 response is missing resource_metadata parameter #1054
   • IsConfiguredEndpointRequest() now properly validates absolute URIs by checking both host and scheme match, not just the path. This may cause previously accepted requests to be rejected if host/scheme don't match.
   • ModelContextProtocol.AspNetCore.Authentication.McpAuthenticationOptions.ResourceMetadataUri was changed from string to a nullable string?.
   • ModelContextProtocol.Authentication.ProtectedResourceMetadata.Resource was changed from required Uri to a non-required and nullable Uri?
4. Remove McpClient.Enumerate*Async methods #1060
   • Removes EnumerateToolsAsync, EnumeratePromptsAsync, EnumerateResourceTemplatesAsync, and EnumerateResourcesAsync from the public API surface. These scenarios are covered by the corresponding List*Async methods.
5. Add McpClient/Session methods using .Protocol types #1063
   • Methods accepting a CancellationToken token had the argument renamed from token to cancellationToken for consistency throughout the SDK.
   • Methods accepting a JsonSerializerOptions? serializerOptions argument were updated to accept a RequestOptions? options argument instead, further adopting the RequestOptions class introduced in #970.
   • ModelContextProtocol.Client.McpClient.CompleteAsync was updated to add an optional RequestOptions? options argument, changing the position of the optional CancellationToken argument on the method signature.
   • ModelContextProtocol.Client.McpClient.UnsubscribeFromResourceAsync arguments were changed to now accept UnsubscribeRequestParams requestParams, CancellationToken cancellationToken = default.
   • ModelContextProtocol.Client.McpClient.SetLoggingLevel was renamed to SetLoggingLevelAsync.

What's Changed

• Add support for Client ID Metadata Documents to enable URL-based client registration #1023 by @MackinnonBuck
• Add Conformance tests for the server #983 by @mikekistler
• Adjust analyzer diagnostic severities and improve MCP001 reporting #1038 by @stephentoub (co-authored by @Copilot)
• Remove obsolete APIs from codebase #985 by @MackinnonBuck (co-authored by @Copilot @eiriktsarpalis @jeffhandley)
• Add support for data to McpProtocolException #1028 by @stephentoub (co-authored by @Copilot)
• Fix XML generator partial method issues #1059 by @jongalloway
• Remove McpClient.Enumerate*Async methods #1060 by @stephentoub (co-authored by @Copilot)
• Add request options bag to high level requests and include Meta #970 by @mikekistler (co-authored by @stephentoub @Copilot)
• Add support for URL mode elicitation #1021 by @halter73
• Synthesize return description into tool description when UseStructuredContent is false #1049 by @stephentoub (co-authored by @Copilot)
• Add ResourceNotFound error code (-32002) #1062 by @stephentoub (co-authored by @Copilot)
• Add McpClient/Session methods using .Protocol types #1063 by @stephentoub
• WithMeta for McpClientTool #1027 by @PederHP (co-authored by @stephentoub)
• Fall back to well-known URL in client if 401 response is missing resource_metadata parameter #1054 by @halter73
• Add DebuggerDisplay attributes to Protocol types #1068 by @stephentoub (co-authored by @Copilot @halter73)
• Add SubscribeToResourceAsync overload with handler delegate #1069 by @stephentoub (co-authored by @Copilot)

Documentation Updates

• Core Protocol docs edit pass #1032 by @gewarren
• MCP Core docs edit pass #1033 by @gewarren (co-authored by @stephentoub)
• Docs edit pass (MCP.AspNetCore and a few other files) #1034 by @gewarren (co-authored by @stephentoub @mikekistler)

Repository Infrastructure Updates

• Bump version to 0.5.0-preview.1 #1035 by @jeffhandley
• Bump the serilog-testing group with 1 update #1046
• Bump actions/setup-dotnet from 5.0.0 to 5.0.1 #1045
• Bump the testing-frameworks group with 1 update #1044
• Update NuGet.org package owner to ModelContextProtocol #1071 by @jeffhandley

Acknowledgements

• @jongalloway made their first contribution in #1059
• @ochafik submitted #773 (resolved by #1054)
• @eiriktsarpalis @ericstj @goncalveswilliam020-svg @sunnymitramsft reviewed pull requests

Full Changelog: v0.4.1-preview.1...v0.5.0-preview.1

This release brings protocol type standardization, several MCP specification implementations, and new features including an incremental source generator for automatic Description attributes from XML comments and client session resumption support. This release includes breaking changes to protocol types and elicitation enum schemas; refer to the Breaking Changes section below for details.

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 stabilizing the API.

Breaking Changes

Refer to the C# SDK Versioning documentation for details on versioning and breaking change policies.

1. Audit and standardize MCP protocol types for consistency #892
   • Property mutability changes
   • Required properties changes
   • Collection types used for properties
2. Implement SEP-1330: Standards-compliant enum schemas for elicitation #969
   • 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

What's Changed

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

Documentation Updates

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

Test Improvements

• Fix tests in Dev Container #965 by @halter73
• Skip flaky test on Mono where stderr callbacks are unsupported #980 by @stephentoub (co-authored by @Copilot)

Repository Infrastructure Updates

• Update Microsoft.Extensions.AI packages to version 9.10.1 #916 by @stephentoub (co-authored by @Copilot)
• Update to .NET SDK to 10.rc2 #883 by @eiriktsarpalis
• Bump danielpalme/ReportGenerator-GitHub-Action from 5.4.17 to 5.4.18 #920
• Bump actions/upload-artifact from 4.6.2 to 5.0.0 #918
• Bump actions/download-artifact from 5.0.0 to 6.0.0 #919
• Fixed dotnet version from 10.0.100-rc.1.25451.107 to 10.0.100-rc.2 #927 by @eduardomb-aw (co-authored by @eiriktsarpalis)
• Update to .NET 10.x packages #957 by @stephentoub
• Remove prerelease requirement from global.json #961 by @eiriktsarpalis
• Update to MTP #958 by @Youssef1313
• Bump actions/checkout from 5.0.0 to 5.0.1 #973
• Bump danielpalme/ReportGenerator-GitHub-Action from 5.4.18 to 5.5.0 #972
• Bump the opentelemetry-testing group with 6 updates #974
• Revert "Update to MTP" #989 by @eiriktsarpalis
• Bump the serilog-testing group with 2 updates #992
• Bump the testing-frameworks group with 3 updates #991
• Revert "Revert "Update to MTP"" #990 by @Youssef1313
• Add Microsoft.CodeAnalysis.* to dependabot ignore list #1009 by @eiriktsarpalis (co-authored by @Copilot)
• Revert "Update to MTP (#958)" #1011 by @halter73
• Bump the testing-frameworks group with 3 updates #1013
• Bump the serilog-testing group with 1 update #1014
• Bump version to 0.4.1-preview.1 #1031 by @jeffhandley

Acknowledgements

• @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
• @anktsrkr submitted issue #749 (resolved by #834)
• @AlexandreDonne submitted issue #597 (resolved by #834)
• @pankajvaher submitted issue #946 (resolved by #1029)
• @cristipufu submitted issue #621 (resolved by #1029)
• @mikekistler @narasamdya @jozkee reviewed pull requests

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

This release adds icons and metadata support (SEP-973), the new McpMetaAttribute for attaching custom metadata to tools, prompts, and resources, and .NET 10.0 target framework support. It also includes several bug fixes including faster shutdown for Streamable HTTP servers, proper exception propagation through tool call filters, and a fix for templated resource matching. This release contains breaking changes — see below for details and migration guidance.

Breaking Changes

Refer to the C# SDK Versioning documentation for details on versioning and breaking change policies.

1. McpException refactored; ErrorCode and error-code constructors moved to new McpProtocolException #844

   • McpException.ErrorCode property, McpException(string, McpErrorCode), and McpException(string, Exception?, McpErrorCode) constructors were removed. Use McpProtocolException for error-code scenarios.
   • McpException thrown from tools and tool call filters now produces an errored CallToolResult instead of a JSON-RPC error. Use McpProtocolException to produce a JSON-RPC error with a specific error code.

2. McpServerResource.ReadAsync return type changed; new abstract IsMatch method #897

   • McpServerResource.ReadAsync return type changed from ValueTask<ReadResourceResult?> to ValueTask<ReadResourceResult>. Custom subclasses must update their signatures and throw InvalidOperationException instead of returning null for non-matching URIs.
   • New abstract method bool IsMatch(string uri) must be implemented by any custom McpServerResource subclass.

3. StreamableHttpServerTransport method renames #843

   • HandleGetRequest renamed to HandleGetRequestAsync and HandlePostRequest renamed to HandlePostRequestAsync. Update call sites accordingly.

What's Changed

• Implement SEP-973: Icons and metadata support for Implementations, Resources, Tools, and Prompts #802 by @MackinnonBuck (co-authored by @jozkee @Copilot)
• Fix slow shutdown when a Streamable HTTP client is connected #843 by @halter73
• Propagate tool call exceptions through filters #844 by @halter73 (co-authored by @stephentoub)
• Add net10.0 assets and run some fixers #875 by @stephentoub
• Synthesize handlers for empty tool/prompt/resource collections #865 by @stephentoub (co-authored by @Copilot)
• Convert EverythingServer to use Streamable HTTP #709 by @mikekistler (co-authored by @halter73)
• Add McpMetaAttribute for attaching metadata to tools, prompts, and resources #857 by @stephentoub (co-authored by @Copilot)
• Fix regression matching templated McpServerResources #897 by @halter73
• Call Regex.IsMatch when Match is not needed #903 by @halter73

Documentation Updates

• Fix markdown links in docs and add docfx CI validation #862 by @eiriktsarpalis (co-authored by @Copilot)
• Fix comments on McpServerTool/Prompt/Resource #866 by @stephentoub

Test Improvements

• Remove problematic System.Net.Http package reference from tests #867 by @stephentoub
• Add comprehensive test coverage for resource capability preservation with WithResources #896 by @stephentoub (co-authored by @Copilot)

Repository Infrastructure Updates

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

Acknowledgements

• @dsp-ant submitted issue #753 (resolved by #802)
• @codeape2 submitted issue #825 (resolved by #843)
• @gophph submitted issue #820 (resolved by #844)
• @BenLampson submitted issue #821 (resolved by #897)

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