Add request options bag to high level requests and include Meta #970

mikekistler · 2025-11-17T17:27:17Z

Motivation and Context

This PR adds the ability to set fields of the _meta parameter in requests with the high-level request methods.

It also refactored these methods to move several parameters common in request methods -- JsonSerializerOptions, ProgressToken, and the new Meta field -- to an options bag to make these signatures more concise.

How Has This Been Tested?

All tests pass with the revised method signatures.

Breaking Changes

This will be breaking (as currently implemented) for users that specify any of these (uncommonly used) parameters.

Types of changes

Bug fix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)
Breaking change (fix or feature that would cause existing functionality to change)
Documentation update

Checklist

I have read the MCP Documentation
My code follows the repository's style guidelines
New and existing tests pass locally
I have added appropriate error handling
I have added or updated documentation as needed

Additional context

Some new features in the 2025-11-25 version of the MCP spec require setting and reading fields of _meta, e.g. SEP-1686: Tasks. This change will make it easier for users to access these new features.

src/ModelContextProtocol.Core/Client/McpClient.Methods.cs

Copilot

Pull Request Overview

This PR introduces a RequestOptions class to consolidate common optional parameters (Meta, JsonSerializerOptions, and ProgressToken) across MCP client and server request methods. This refactoring reduces method signature complexity and enables setting the _meta field in requests, which is needed for new MCP spec features like SEP-1686 (Tasks).

Key Changes

Added new RequestOptions class to hold optional request parameters
Updated all client and server request method signatures to accept RequestOptions instead of individual parameters
Created PingRequestParams protocol class for structured ping requests
Updated tests to use the new method signatures with named parameters or null for options

Reviewed Changes

Copilot reviewed 32 out of 33 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
src/ModelContextProtocol.Core/RequestOptions.cs	New options bag class with Meta, JsonSerializerOptions, and ProgressToken properties
src/ModelContextProtocol.Core/Protocol/PingRequestParams.cs	New protocol parameter class for ping requests
src/ModelContextProtocol.Core/Client/McpClient.Methods.cs	Updated all client methods to accept RequestOptions and properly set Meta in request params
src/ModelContextProtocol.Core/Server/McpServer.Methods.cs	Updated SampleAsync and RequestRootsAsync to accept RequestOptions
src/ModelContextProtocol.Core/Client/McpClientExtensions.cs	Updated extension methods to wrap individual parameters in RequestOptions
src/ModelContextProtocol.Core/Server/McpServerExtensions.cs	Updated extension methods to forward calls with named parameters
src/ModelContextProtocol.Core/Client/McpClient*.cs	Updated client wrapper classes to construct RequestOptions when calling client methods
src/ModelContextProtocol.Core/McpJsonUtilities.cs	Added PingRequestParams to source generation context
tests/*/.cs	Updated all test call sites to use new signatures with null or named parameters
samples/*/.cs	Updated sample code to use named parameters for cancellationToken

src/ModelContextProtocol.Core/Server/McpServer.Methods.cs

tests/ModelContextProtocol.Tests/Client/McpClientExtensionsTests.cs

tests/ModelContextProtocol.Tests/Client/McpClientTests.cs

src/ModelContextProtocol.Core/Client/McpClientTool.cs

src/ModelContextProtocol.Core/RequestOptions.cs

stephentoub · 2025-11-20T03:47:36Z

src/ModelContextProtocol.Core/Server/McpServer.Methods.cs

    {
        ThrowIfRootsUnsupported();

+        if (options?.Meta is not null)


If this kind of merging will need to be done in more than one place, we should have a helper for it.

It is currently done in two places, though I'm not quite sure why it doesn't also occur for ElicitAsync. What would a helper look like for this code?

I think this exposes a bug - the ElicitRequestParams should extend RequestParams, just as ListRootsRequestParams and CreateMessageRequestParams do. And ElicitAsync should accept RequestOptions to set Meta. I'll work on that.

I'm doing meta merging on the client side in the PR to extend McpClientTool with a WithMeta method. I think this merging meta objects might become more and more common, as meta seems to be a popular place to put new fields, and remain backwards compatible even with strict schema validation.

See also the MCP Apps extension in review, it uses meta (on the tool definition) to provide the app UI resource. So, I think a shared helper would be helpful.

I think this exposes a bug - the ElicitRequestParams should extend RequestParams

Agreed. I think this was just an oversight which will be fixed as part of #1021

mikekistler · 2025-11-24T05:41:25Z

src/ModelContextProtocol.Core/Protocol/RequestParams.cs

+    public JsonObject? Meta {
+        get;
+        set
+        {
+            // If progressToken is already set in Meta and not present in the new value, preserve it.
+            if (field?["progressToken"] is JsonValue existingProgressToken &&
+                (value is null || !value.ContainsKey("progressToken")))
+            {
+                // Create a copy to avoid modifying the input parameter
+                field = value is null ? [] : new JsonObject(value);
+                field["progressToken"] = existingProgressToken;
+            }
+            else
+            {
+                field = value;
+            }
+        }
+    }


@stephentoub This is my attempt to address the footgun of possibly setting Meta after setting ProgressToken. I'm not sure I love it but I think it's better than what we had previously.

mikekistler · 2025-11-24T05:42:46Z

src/ModelContextProtocol.Core/Server/McpServer.Methods.cs

    /// <exception cref="InvalidOperationException">The client does not support sampling.</exception>
    public async Task<ChatResponse> SampleAsync(
-        IEnumerable<ChatMessage> messages, ChatOptions? options = default, CancellationToken cancellationToken = default)
+        IEnumerable<ChatMessage> messages, ChatOptions? chatOptions = default, CancellationToken cancellationToken = default)


I had to rename this parameter to chatOptions to disambiguate with the RequestOptions option parameter that I've added on all the requests.

stephentoub · 2025-11-24T14:32:46Z

src/ModelContextProtocol.Core/Protocol/RequestParams.cs

+        get;
+        set
+        {
+            // If progressToken is already set in Meta and not present in the new value, preserve it.


Would it help or hurt if we removed the setter from ProgressToken? Setting the PT would require setting Meta, and the ProgressToken getter would just be there as an accelerator. Presumably the 99.9% case of using the setter is in our own infrastructure?

Hard to know if there are uses of the setter outside of the SDK. Within the SDK there wre only two places I had to change.

Even though this might break some users, I think this is a much better change as it eliminates the footgun that currently exists. I'll push this up shortly.

+1 for removing the ProgressToken setter. Having multiple property setters conditionally configuring the same fields is a recipe for confusion. With the current code, the following wouldn't reset _meta back to null even though it looks like it should.

callToolParams.Meta = new JsonObject() { ["progressToken"] = "foo", }; // The following is surprisingly a no-op. The "progressToken" stays. callToolParams.Meta = null;

Another option would be to store ProgressToken in its own field and only merge it into the _meta object or read it from the _meta object during JSON (de)serialization using a custom converter, but the downside is that you couldn't see the real value of _meta after setting the ProgressToken, and the ProgressToken property might be null even after someone manually sets it via the Meta property.

I think I prefer just removing the ProgressToken setter. In the unlikely event that non-SDK code is broken by the setter removal, at least it should be obvious what's going on with the compile time failure.

mikekistler · 2025-11-24T16:20:03Z

src/ModelContextProtocol.Core/Server/McpServer.Methods.cs

    /// <exception cref="InvalidOperationException">The client does not support sampling.</exception>
    public ValueTask<CreateMessageResult> SampleAsync(
-        CreateMessageRequestParams request, CancellationToken cancellationToken = default)
+        CreateMessageRequestParams request, RequestOptions? options = null, CancellationToken cancellationToken = default)


I added RequestOptions here but I'm only using the Meta field from this. The JsonSerializationOptions and ProgressToken, if set, are ignored. That's because the existing code did not use either of these. But should it?

@eiriktsarpalis Should we be accepting / using JsonSerializationOptions on the server-to-client request methods (ListRootsAsync, SampleAsync, and ElicitAsync)? How would we use these options?

mikekistler commented Nov 17, 2025

View reviewed changes

src/ModelContextProtocol.Core/Client/McpClient.Methods.cs Show resolved Hide resolved

mikekistler requested a review from Copilot November 17, 2025 21:35

Copilot started reviewing on behalf of mikekistler November 17, 2025 21:35 View session

Copilot finished reviewing on behalf of mikekistler November 17, 2025 21:37

Copilot AI reviewed Nov 17, 2025

View reviewed changes

mikekistler requested a review from halter73 November 17, 2025 22:01

stephentoub reviewed Nov 20, 2025

View reviewed changes

src/ModelContextProtocol.Core/Client/McpClientTool.cs Outdated Show resolved Hide resolved

stephentoub reviewed Nov 20, 2025

View reviewed changes

src/ModelContextProtocol.Core/RequestOptions.cs Outdated Show resolved Hide resolved

stephentoub reviewed Nov 20, 2025

View reviewed changes

src/ModelContextProtocol.Core/RequestOptions.cs Outdated Show resolved Hide resolved

stephentoub reviewed Nov 20, 2025

View reviewed changes

mikekistler added 9 commits November 23, 2025 20:53

Remove trailing whitespace to make the real changes easier to review

384517a

Copliot changes to add meta to high-level methods

9656dcf

Fix core build breaks

72b640d

Clean build

72f56c3

Fix tests

c22fe87

Minor cleanup

cbdf649

Fix obscure bug in constructor

63a4749

Address PR review comments

80ed2c3

Rebase to latest main

4ed55e6

mikekistler force-pushed the mdk/expose-meta branch from dc24e39 to 4ed55e6 Compare November 24, 2025 05:29

mikekistler commented Nov 24, 2025

View reviewed changes

mikekistler requested a review from stephentoub November 24, 2025 05:44

stephentoub reviewed Nov 24, 2025

View reviewed changes

mikekistler commented Nov 24, 2025

View reviewed changes

mikekistler mentioned this pull request Nov 25, 2025

Helper method to merge additional metadata into requests, results, and notifications #1030

Open

9 tasks

Add request options bag to high level requests and include Meta #970

Are you sure you want to change the base?

Add request options bag to high level requests and include Meta #970

Conversation

mikekistler commented Nov 17, 2025

Motivation and Context

How Has This Been Tested?

Breaking Changes

Types of changes

Checklist

Additional context

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Key Changes

Reviewed Changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

PederHP Nov 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

PederHP Nov 25, 2025 •

edited

Loading