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]

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

[Jaorow]

Hey @samchenatti
This is awesome and really helps out with something im trying to build!

Do you have an ETA on when this might be in?

[samchenatti]

Hey @Jaorow!

I'm waiting on the maintainers’ feedback...

This feature has become even more important since OpenAI announced the App SDK.
They’re making heavy use of _meta to enable UI components.

By merging this PR, we’d allow other MCP Clients to do the same.

[maxisbey]

Look good! Although, I'd want to see some unit tests for this. You could add them in tests/server/test_session.py

[Jaorow]

Hey @Jaorow!

I'm waiting on the maintainers’ feedback...

This feature has become even more important since OpenAI announced the App SDK. They’re making heavy use of _meta to enable UI components.

By merging this PR, we’d allow other MCP Clients to do the same.

@samchenatti Awesome, It will definitely open the door for more complex and structured functionality.

[samchenatti]

Hey, @maxisbey!

I made the requested changes and implemented the unit test.

I had to cheat a bit in the test and manually set _tool_output_schemas

After a good night’s sleep, I was able to properly implement the unit test (commit 2b61abba).

Now the client and server exchange all the necessary messages just like they would in a real scenario.

[samchenatti]

@maxisbey thanks for the approval!

@ihrpr, @dsp-ant can you guys also take a look on my changes?

dismissing my own review