Allow clients to send _meta to server

[samchenatti]

Enhancement Description

Hello, guys!

First, thanks (and congrats) for the great work on FastMCP!

Since @jlowin’s PR #1294, servers are now allowed to send metadata in the _meta field to clients.

I’d like to propose (and possibly implement) support for the opposite direction: allowing clients to send _meta arguments to the server.

Use Case

Agents sometimes need to send data during tool calls that don’t qualify as function arguments or HTTP headers. This information could be, for example, user preferences and might determine how tools (and other resources such as prompts) are processed in the server.

In any case, the protocol specification does not forbid MCP clients from sending _meta to MCP servers, so I believe this wouldn't be a bad design decision.

Are there any alternative solutions you've considered?
I’ve considered using HTTP request headers, but I don’t think that would cover all use cases and security necessities.

Proposed Implementation

Since FastMCP relies on SDK's ClientSession.call_tool interface, it would be required to directly use ClientSession.send_request (unless _meta is also exposed in the SDK)

    async def call_tool_mcp(
        self,
        name: str,
        arguments: dict[str, Any],
        progress_handler: ProgressHandler | None = None,
        timeout: datetime.timedelta | float | int | None = None,
        meta: dict | None = None # <-- Expose meta in the public interface
    ) -> mcp.types.CallToolResult:
        if isinstance(timeout, int | float):
            timeout = datetime.timedelta(seconds=timeout)

        # Since self.session.call_tool doesn't expose meta, it would be required to directly use self.session.send_request
        result = await self.session.send_request(
            types.ClientRequest(
                types.CallToolRequest(
                    method="tools/call",
                    params=types.CallToolRequestParams(
                        name=name,
                        arguments=arguments,
                        meta=meta <-- Pass metadata down to the MCP SDK
                    ),
                )
            ),
            types.CallToolResult,
            request_read_timeout_seconds=read_timeout_seconds,
            progress_callback=progress_callback,
        )
        return result

[jlowin]

I would love this but I'm very hesitant to reimplement the low-level tool calls, as it creates a huge maintenance burden on FastMCP to also keep up with low-level changes. I'd prefer to wait until it is added in mcp and then make sure it is exposed in a user-friendly way!

[hopeful0]

This presents an excellent approach for sharing state between client and server. I have a related idea that might help avoid the maintenance burden.

I want exposing only a state dictionary within the meta, rather than the entire meta object. This state dictionary could be stored in either the client session or client context.

We would then override the send_request method to inject this state dictionary into request.params.meta before invoking the low-level send_request. On the server side, fastmcp could persist this state dictionary in the server context for direct access by middleware or tools.

[slevental]

@samchenatti were you able to make it work on the MCP Server side? Even after adding the explicit _meta attribute, the server side deserialization seemed to ignore it and there is no way to retrieve it from the context. Maybe I'm missing something, but if you have corresponding FastMCP Server side snippet - it would be very helpful!

[samchenatti]

Hey, @slevental !

I can access meta on the server by using the following snippet (fastmcp==2.10.6):

mcp = FastMCP('Sample')

@mcp.tool()
async def sample_tool(context: Context = None):
    logger.info(context.request_context.meta)

If you are using curl to issue a request, be sure to put _meta inside params (this was not clear from the MCP specification):

curl  -L -X POST "http://127.0.0.1:9090/mcp" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "id": 1,
    "params": {
        "name": "sample_tool",
        "arguments": {
        },
        "_meta": {
            "foo": 1
        }
    }
  }'

Also, if you are interested in this feature, please like my PR in the python-sdk!

[slevental]

@samchenatti Thank you so much, I've already liked your PR - thanks for doing it!