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

0.2.0-preview.1

What's Changed

• Bump version to 0.2.0-preview.1 by @jeffhandley in #417
• Update to stable M.E.AI :) by @stephentoub in #421
• Fix NRT annotation on StdioClientTransportOptions.EnvironmentVariables by @stephentoub in #419
• Remove internal GetBase64Data helper by @stephentoub in #422

Full Changelog: v0.1.0-preview.14...0.2.0-preview.1

v0.1.0-preview.14

What's Changed

• Make small corrections to release process docs by @jeffhandley in #402
• Bump next version to preview.14 by @jeffhandley in #403
• Update M.E.AI.Abstractions to 9.5.0-preview.1.25262.9 by @stephentoub in #412
• Add stateless Streamable HTTP support by @halter73 in #392
• Fix McpServerResource registration by @stephentoub in #411
• Improve exception diagnostics for stdio client by @stephentoub in #376
• Clean up namespaces by @stephentoub in #410

Full Changelog: v0.1.0-preview.13...v0.1.0-preview.14

v0.1.0-preview.13

What's Changed

• Set IsError on CallToolResponse to true when result is ErrorContent by @Astaggrock in #394
• Add McpServer/ClientResource{Template} and friends by @stephentoub in #391
• Use WithResources in EverythingServer sample by @stephentoub in #400
• Update to latest M.E.AI version by @stephentoub in #401

New Contributors

• @Astaggrock made their first contribution in #394

Full Changelog: v0.1.0-preview.12...v0.1.0-preview.13