Field alias is published in the tool schema but forwarded as an invalid Python keyword

[destire-mio]

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

[nightcityblade]

Hi, I'd like to work on this. I'll submit a PR shortly.

[IgorGanapolsky]

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:

1. Dump tool schema (what the agent sees) vs actual function signature / pydantic model field names.
2. Call the tool outside the agent with both the alias and the real keyword — which one succeeds?
3. Redacted failing run: schema snippet + TypeError/validation error + whether a non-agent call works.

That separates “model chose wrong field” from “schema lied about the callable surface.”

[nightcityblade]

I reviewed the contribution guidelines and will wait for maintainer feedback or assignment before starting implementation.

[zerafachris]

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-supplied Field(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 apply ready for work?

[jayzuccarelli]

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.