v0.4.0-preview.3

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