Support passing metadata (_meta) in MCP tool calls

[pshopper]

Feature request

Is your feature request related to a problem?

When using MCP servers with the Agents SDK, there is no way to pass metadata (_meta) with tool call requests. The MCP protocol supports a _meta field in CallToolRequest (see MCP spec - Calling tools), which allows clients to include additional context such as:

• Request correlation IDs for debugging and distributed tracing
• User context (locale, session info) for MCP servers that need request-specific behavior

Currently, the MCPServer.call_tool() method signature is:

async def call_tool(self, tool_name: str, arguments: dict[str, Any] | None) -> CallToolResult

This prevents users from leveraging the full MCP protocol capabilities when invoking tools.

Describe the solution you'd like

Add an optional meta parameter to MCPServer.call_tool():

async def call_tool(
    self,
    tool_name: str,
    arguments: dict[str, Any] | None,
    meta: dict[str, Any] | None = None,
) -> CallToolResult

The meta parameter should be passed through to the underlying MCP ClientSession.call_tool() method, which already supports it (as of mcp>=1.19.0).

Describe alternatives you've considered

1. Subclassing _MCPServerWithClientSession — requires duplicating significant implementation code and accessing private APIs
2. Using session.send_request() directly — bypasses the SDK's retry logic and error handling
3. Patching the session object — fragile and not recommended for production use

None of these alternatives provide a clean, supported way to pass metadata.

Additional context

Example use case — passing request context for debugging and tracing:

server = MCPServerStreamableHttp(name="worker", params={"url": "http://localhost:8000/mcp"})
await server.connect()

# Pass request metadata for tracing and debugging
result = await server.call_tool(
    "search_documents",
    {"query": "quarterly report"},
    meta={"requestId": "req-abc-123", "locale": "en-US"}
)

The MCP library (mcp>=1.19.0) already supports the meta parameter in ClientSession.call_tool(), so this change would align the Agents SDK with the underlying library capabilities.

Related

• MCP Specification: https://modelcontextprotocol.io/specification/2025-11-25/basic#general-fields
• MCP Python SDK changelog for meta support: https://github.com/modelcontextprotocol/python-sdk/releases/tag/v1.19.0

[pshopper]

@rm-openai @seratch
Could you please take a look when you have a moment?

There is a proposed solution in PR #2366 that adds support for passing meta through MCPServer.call_tool() and aligns the SDK with the MCP protocol and mcp>=1.19.0.

Happy to iterate on the approach if needed — any feedback would be appreciated.

[seratch]

@pshopper Adding the optional parameter itself is fine, but in reality, this Agents SDK does not relay the metadata within an agent run. So, I think this does not resolve any real-world use cases, and it simply improves the internal module's feature parity with MCP protocol. Can you elaborate more on why this is necessary for you?

[pshopper]

@pshopper Adding the optional parameter itself is fine, but in reality, this Agents SDK does not relay the metadata within an agent run. So, I think this does not resolve any real-world use cases, and it simply improves the internal module's feature parity with MCP protocol. Can you elaborate more on why this is necessary for you?

@seratch Thanks for the clarification. This is not only about feature parity, but about aligning the Agents SDK with how MCP is actually used in practice.

There are concrete, documented examples in the MCP ecosystem where _meta is treated as a separate execution context, not mixed with tool arguments:

• Databricks Vector Search MCP servers — the Databricks documentation explicitly describes _meta parameters used to control server behavior (such as result limits, filters, and column selection) independently of the model-generated tool arguments. This clearly demonstrates _meta as runtime-provided context rather than model input.
  https://docs.databricks.com/aws/en/generative-ai/mcp/managed-mcp-meta-param

• OpenAI Apps SDK — MCP interactions include request-scoped metadata (request IDs, user/session context, locale, client information) alongside tool calls, with a clear separation between tool arguments and execution context.
  https://platform.openai.com/docs/apps

Across these systems, metadata is provided by the runtime rather than the model and should not live in tool arguments. Values such as request IDs, user or tenant identifiers, tracing context, or locale should not be generated or modified by the model, nor pollute the semantic contract of the tool.

Exposing _meta in MCPServer.call_tool() therefore makes the Agents SDK a more complete MCP client, avoids fragile workarounds, and prevents users (including myself) from having to look for alternative Python SDKs or maintain custom forks solely to propagate request-scoped execution context reliably.

[seratch]

I also understand _meta is widely used. My point here is that Agents SDK does not provide the _meta even if the MCP server wrapper accepts it. So, just adding the arguments is not a meaningful enhancement. I'd like to know what's the real use cases with it and how this SDK can properly support it. The non-hosted MCP server tools are internally treated in the same way with function tools. So, there is no consideration of additional _meta context data at this moment.

[pshopper]

@seratch First and foremost, this is required for observability use cases, such as distributed tracing, request correlation, and log linkage. Additionally, it is needed to propagate user identifiers into MCP tools, so that tools can be aware of the user context.

[pshopper]

For completeness, I already have a PR #2366 with an implementation and tests that improves the SDK, if that would be useful.

[seratch]

Thanks for sharing these. I have already reviewed your PR.

You may be thinking of using the MCP server wrapper provided by this SDK directly, but the MCP server classes are intended to be called from within an agent loop. So even if this SDK includes the optional parameter you added in the PR, the _meta parameter will not be propagated in most use cases. As long as an enhancement does not natively fit the SDK's main use cases, we would like to avoid adding complexity to the codebase, even if it is minor.

[pshopper]

@seratch I should also clarify that I use this SDK both for direct MCP calls and within an agent loop, as part of a broader internal setup with additional abstractions around it. Unfortunately, I can’t share the concrete implementation details due to commercial constraints.

Supporting this use case would make the SDK usable for a wider set of real-world integrations, including mine, and would allow more users to adopt it without forks or workarounds. In turn, this typically leads to more feedback, bug reports, and improvement proposals from production users.

[seratch]

Thanks for sharing. However, based on the information provided, I still do not see an immediate need to add this parameter, since it would not be used within an agent loop, and I cannot think of a concrete use case for it at the moment. If you want to use MCP servers outside of agent runs in this SDK, please use the MCP SDK directly. Again, this SDK's MCP server wrapper is focused on agent-run scenarios. We do not intend to build and maintain a fully featured wrapper.

I will keep this issue open for a while. If anyone has a different idea or a use case, please feel free to share.

[pshopper]

@seratch I have a question about the possible approach. I noticed that:

Current state

1. list_tools() already receives run_context:

   async def list_tools(
       self,
       run_context: RunContextWrapper[Any] | None = None,
       agent: AgentBase | None = None,
   ) -> list[MCPTool]:

2. But call_tool() does not:

   async def call_tool(self, tool_name: str, arguments: dict[str, Any] | None) -> CallToolResult:

Question

Would it be acceptable to extend the implementation so that:

1. Add run_context parameter to call_tool() (similar to how list_tools() already works)
2. Introduce a protocol/interface (e.g., HasMCPMeta) that users can implement on their context object
3. Extract _meta from context automatically and pass it to the underlying MCP session.call_tool()

This would allow users to define metadata once in their context:

@dataclass
class MyContext:
    request_id: str
    user_id: str

    def get_mcp_meta(self) -> dict[str, Any]:
        return {
            "request_id": self.request_id,
            "user_id": self.user_id,
        }

context = MyContext(request_id="abc-123", user_id="user-456")
result = await Runner.run(agent, "query", context=context)
# _meta automatically flows to all MCP tool calls

This approach:

• Fits naturally into the existing SDK patterns (context is already used for tool filtering)
• Doesn't require changes to RunConfig or new configuration surfaces
• Allows request-scoped metadata to flow through the agent loop automatically

Would this be a meaningful enhancement worth pursuing? Happy to extend my PR if so.

[seratch]

An agent loop could have multiple MCP servers, so if you pass _meta for MCP servers, the data structure would be {"<server name>": { "<tool name>": {"request_id": "123"} } or {"<server name>": {"request_id": "123"} (if you pass the same to all tools of the server). I don't think this could be used a lot in real-world apps. An alternative idea is to enable pass a static _meta dat when spinning an MCP server up, but this does not allow sending a different data per request unless you start a new MCP server connection per request. Either way, I'd like to hold off doing any of these unless many developers need such.