Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/modelcontextprotocol/csharp-sdk/llms.txt

Use this file to discover all available pages before exploring further.

The Model Context Protocol C# SDK uses the [Experimental] attribute to mark APIs that are still in development and may change without notice.
Experimental APIs may change at any time—including within PATCH or MINOR version updates. See the Versioning documentation for the SDK’s versioning policy.

​
Suppressing Experimental Diagnostics

When you use an experimental API, the compiler produces a diagnostic (e.g., MCPEXP001) to ensure you’re aware the API may change. If you want to use the API, suppress the diagnostic in one of these ways:

​
Project-Wide Suppression

Add the diagnostic ID to <NoWarn> in your project file: 
<PropertyGroup>
  <NoWarn>$(NoWarn);MCPEXP001</NoWarn>
</PropertyGroup>
This approach is recommended when you’re actively using experimental features throughout your project.

​
Per-Call Suppression

Use #pragma warning disable around specific call sites: 
#pragma warning disable MCPEXP001 // The Tasks feature is experimental per the MCP specification and is subject to change.
tool.Execution = new ToolExecution { ... };
#pragma warning restore MCPEXP001
This approach provides more granular control and makes it clear which specific code depends on experimental APIs.
For a full list of experimental diagnostic IDs and their descriptions, see the list of diagnostics in the SDK documentation.

​
Serialization Behavior

Experimental properties on protocol types are fully serialized and deserialized when using the SDK’s built-in serialization via McpJsonUtilities.DefaultOptions. This means experimental data is transmitted on the wire even if your application code doesn’t directly interact with it, preserving protocol compatibility.

​
Reflection-Based vs. Source-Generated Serialization

The behavior of experimental properties differs depending on whether you use reflection-based or source-generated serialization:

Reflection-Based

Default behavior when no JsonSerializerContext is used. Experimental properties are included automatically with no special configuration needed.

Source-Generated

When using a custom JsonSerializerContext, experimental properties are not included in your context’s serialization contract by design, protecting against binary breaking changes.
Switching between reflection-based and source-generated serialization can silently change which properties are serialized. To avoid this, source-generation users should configure a TypeInfoResolverChain as described below.

​
Custom JsonSerializerContext

If you define your own JsonSerializerContext that includes MCP protocol types, configure a TypeInfoResolverChain so the SDK’s resolver handles MCP types: 
using ModelContextProtocol;

JsonSerializerOptions options = new()
{
    TypeInfoResolverChain =
    {
        McpJsonUtilities.DefaultOptions.TypeInfoResolver!,
        MyCustomContext.Default,
    }
};
By placing the SDK’s resolver first, MCP types are serialized using the SDK’s contract (which includes experimental properties), while your custom context handles your own types.
This configuration is recommended even if you aren’t currently using experimental APIs, since it ensures your serialization configuration remains correct as new experimental properties are introduced or as you adopt experimental features in the future.

​
Current Experimental Features

​
Tasks

The Tasks feature is experimental per the MCP specification and is subject to change. Tasks allow servers to manage long-running operations with progress tracking and cancellation support. To use the Tasks feature, you’ll need to suppress the MCPEXP001 diagnostic as shown above.

​
Best Practices

Experimental APIs may change or be removed in future releases. Only use them if you’re comfortable with potential breaking changes in your code.
Don’t suppress experimental diagnostics globally without understanding which APIs you’re using and why they’re experimental.
If using source-generated JSON serialization, always configure the TypeInfoResolverChain to include the SDK’s resolver.
Monitor SDK release notes and the roadmap to track when experimental APIs stabilize or change.

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us