Repository navigation
Field alias is published in the tool schema but forwarded as an invalid Python keyword #3099
Description
Initial Checks
- I confirm that I'm using the latest version of MCP Python SDK.
- I confirm that I searched the issue tracker before opening this issue.
Description
For a function parameter annotated with Field(alias="externalX"), the generated tool schema correctly requires externalX. At runtime, however, that wire name is forwarded directly to the original function, so the call fails with:
ToolError: Error executing tool f: f() got an unexpected keyword argument 'externalX'
I expected the schema-valid input to be mapped back to the Python parameter x before invocation.
Example Code
import asyncio
from typing import Annotated
try:
from mcp.server.mcpserver.tools.base import Tool
except ImportError: # MCP Python SDK 1.x
from mcp.server.fastmcp.tools.base import Tool
from pydantic import Field
AliasInt = Annotated[int, Field(alias="externalX", ge=1)]
def f(x: AliasInt) -> int:
return x
async def main() -> None:
tool = Tool.from_function(f)
print(tool.parameters)
print(await tool.run({"externalX": 1}, None))
asyncio.run(main())The printed schema requires externalX, then the call fails with the error above.
Python & MCP Python SDK
Stable reproduction:
- Python 3.13.13
- mcp 1.28.1
- pydantic 2.13.4
Current main reproduction:
- modelcontextprotocol/python-sdk commit 2713b53b127afc094dc97d6067df9f69b647661c
- mcp 2.0.0b2
- mcp-types 2.0.0b2
- Python 3.13.13
Activity
nightcityblade commentedon Jul 16, 2026
Hi, I'd like to work on this. I'll submit a PR shortly.
IgorGanapolsky commentedon Jul 16, 2026
This is another tool-schema contract issue: the published JSON Schema advertises a field alias, but the Python call path still forwards the alias as if it were a valid keyword argument — so the tool “exists” in the agent’s schema while the runtime rejects or mis-binds the name.
Isolation that usually resolves it in one pass:
That separates “model chose wrong field” from “schema lied about the callable surface.”
nightcityblade commentedon Jul 17, 2026
I reviewed the contribution guidelines and will wait for maintainer feedback or assignment before starting implementation.
zerafachris commentedon Jul 17, 2026
I'd like to work on this — I've root-caused it (
model_dump_one_level()conflates the SDK's internal reserved-name alias workaround with a user-suppliedField(alias=...), using the alias as the call-time keyword in both cases) and have a fix + regression test ready to submit. Could a maintainer assign this to me or applyready for work?jayzuccarelli commentedon Jul 20, 2026
Just flagging that a fix for this already exists in #3119 (opened Jul 17, CI green). It is still marked draft because of the repo's open-PR limit for non-write contributors, not because it is unfinished. Reuse or ignore it as suits whoever picks this up.
mturac commentedon Aug 30, 2026
I'd like to work on this. I have a fix ready that tracks the original parameter names in a ClassVar and uses them in model_dump_one_level(), so the alias is published in the schema but the Python name is forwarded to the function.
jayzuccarelli commentedon Aug 30, 2026
Could a maintainer assign this one? #3119 has the fix, open since Jul 17 with CI green. It predates the intake gate so it was never assignment-checked. I'll rebase onto main and mark it ready as soon as it's assigned.
Several people have offered here, so no objection if you'd rather assign someone else. Worth knowing the fix already exists either way.