v0.5.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