Expose RequestParams._meta in ClientSession.call_tool

[samchenatti]

Motivation and Context

This change allow clients to send metadata through the _meta field as specified by the protocol.

It is important to expose _meta since there might be some metadata required by the server to control how the tool works (such as client preferences, its localization and so on). In some cases we also don't want the Agent/LLM to be aware of such data; it should be known by the MCP Host and Server only; therefore it cannot be exposed as tool usual arguments.

This feature has already been requested by me and another user - so it might benefit another people as well.

I also started a discussion about _meta being exposed by FastMCP Client, but they will wait until its implemented in here.

How Has This Been Tested?

I tested it on my local environment using a self-made MCP Server.

Since _meta is currently being used for progress report tokens, I also ensured this feature doesn't break progress_callback.

I'd be happy to implement the required unit-tests if someone can point the best test-file for it.

Breaking Changes

There are no breaking changes. The python-sdk already considers that _meta can carry data other than progressToken.

Also types.RequestParams.Meta model is already configured to allow extra key-values.

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

I decided to expose meta as a plain dict instead of types.RequestParams.Meta since, from my understanding, mcp.types shouldn't be exposed to final users.

Metadata could be exposed by another interfaces as well, such as list_tools, list_prompts and etc. I'm sticking with tool_call for now, but would be happy to replicate it to the other interfaces.

[dsp-ant]

I am okay with this change, but I think we should make the ordering such that it's BC compatbile, and create a follow up for the SDK version 2.0 to reconsider the ordering and force named arguments.

[danielabonfim]

This feature looks great and would be a valuable addition. Nice work! Would it be possible to get this approved for merge @dsp-ant

[samchenatti]

Hey, @dsp-ant!

Are there any other changes I need to make?

[discorev]

I'd also be interested in this, is there anything further that needs changing?

[samchenatti]

Hey, @dsp-ant, @ihrpr!

Is there anything else I need to fix in order to get this PR merged?

[aadarshsingh191198]

I'd also be interested in this! Requesting maintainers to merge it if there are no unwanted side effects of this change.

[maeryo]

Great work @samchenatti! This feature would be really valuable for the MCP ecosystem. I hope the conflicts can be resolved soon and this PR gets merged. The community clearly supports this addition based on all the positive feedback. Keep up the excellent work! 🚀

[felixweinberger]

Feedback looks addressed to me but still requires some conflict resolution (apologies for the time it took to get back to this).

If you have time @samchenatti to update PR here and resolve conflicts that'd be greatly appreciated, otherwise I'll aim to get to it later this week!

[samchenatti]

Thanks for the feedback, @maeryo and @felixweinberger!

I'll fix the conflicts by the end of the day

[samchenatti]

@felixweinberger, @maeryo conflicts solved!

[maeryo]

cool! I also checked today and noticed that the kotlin-sdk didn’t have this implementation yet, so I submitted a PR with a similar approach to yours. In addition to just adding the meta parameter, I paid extra attention to improving validation logic as well.

modelcontextprotocol/kotlin-sdk#289

[samchenatti]

Hey, @maeryo, thanks for the feedback!

As suggested, I've implemented the validation here as well, but with a different approach.

Instead of validating _meta in the tool call only, I've implemented the validation directly within the types.RequestParams.Meta model. This seems more appropriate from a Pydantic standpoint.

I've also added unit tests with positive and negative keys, so you can confirm that all the rules are covered.

Note: Please be aware that these validations could be a breaking change, since users may already have non-conformant metadata keys in use.

Edit: I think it is a better idea to make a new PR focusing on the metadata key validation; see #1397

[samchenatti]

@felixweinberger @ihrpr let me know if there's anything else i need to change!