Feature request: Pass metadata to MCP server tool calls

[alex-panther]

Description

Proposed amendment to the runtool function within _agent_graph.py

model_args = args  # Parameters generated by large language models (LLMs)
client_deps = ctx.deps  # Locally passed client parameters
merged_arguments = {**model_args, **client_deps}  # type: ignore
result = await server.call_tool(tool_name, merged_arguments)  # type: ignore

Key Improvements

1. ​​Parameter Merging Mechanism​​

Combines LLM-generated arguments (model_args) with local client dependencies (ctx.deps) using dictionary unpacking

2. ​​Precedence Rule​​

Implements override logic where client_deps values take priority over conflicting model_args

​​3. Context Preservation​​
Maintains type safety through # type: ignore annotations while enabling local parameter propagation to MCP server
Technical Rationale

This modification addresses the current limitation where:

MCP servers receive only LLM-generated parameters

Local context variables (ctx.deps) remain inaccessible at server-side
Client-specific configurations (auth tokens, environment variables) require workarounds

The merged dictionary approach aligns with Pydantic-AI's dependency injection system while maintaining MCP protocol compliance

. Implementation would enhance scenarios like:

ctx.deps = {"api_key": "SECRET_123"} 

Server-side: Directly access merged_arguments['api_key']
Instead of separate auth handling10

References

No response

[DouweM]

@alex-panther I think it'd be unexpected to both users and MCP servers if we unconditionally passed all of the deps. Note also that deps may not be serializable.

I can see the value of being able to modify the arguments sent to the MCP server, though, where "modify" can also mean "add". We already have a prepare_tools hook that allows the tool definition (including schema) to be modified, so it'd make sense to allow the actual tool call to be modified as well.

Would a new hook that takes ctx and args and lets you output new args work for you?

[alex-panther]

@DouweM Yes, it would be great if the new hook allows users to pass custom parameters from the ctx to the MCP server.

[DouweM]

@alex-panther OK. Would you be up to submitting a PR for this?

[anirbanbasu]

@DouweM MCP servers can also attach metadata to their responses. Currently, there isn't a way to capture those in Pydantic AI, if I am correct?

[DouweM]

@anirbanbasu That's correct, but there's a ToolReturnPart.metadata field we could store it on. Can you please file a new issue?

[anirbanbasu]

@DouweM thanks, just did: #3323