FastMCP crashes when tool return type uses Python 3.10+ `A | B | C` union syntax

[Swcmb]

Initial Checks

• I confirm that I'm using the latest version of MCP Python SDK
• I confirm that I searched for my issue in https://github.com/modelcontextprotocol/python-sdk/issues before opening this issue

Description

FastMCP crashes on startup when a tool function's return type annotation uses Python 3.10+ union syntax (A | B | C, i.e. types.UnionType). The error originates from _create_wrapped_model in func_metadata.py, which passes the union annotation directly to Pydantic's create_model() as a bare keyword value, causing PydanticUserError.

Example Code

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("test")

@mcp.tool()
async def my_tool(flag: bool) -> dict | list | str:  # <-- triggers the bug
    if flag:
        return {"key": "value"}
    return ["item"]

Python & MCP Python SDK

- mcp (Python): latest (>=1.0.0,<2.0.0)
- pydantic: >=2.10 (observed on 2.10.x)
- Python: >=3.10

[Swcmb]

Discovery Process

While developing a local MCP tool server with FastMCP, the server immediately crashed on startup with a PydanticUserError. The error message pointed to the result = dict | list | str field in a dynamically generated Pydantic model. Tracing the call stack backward:

1. The error came from pydantic's create_model() in _create_wrapped_model.
2. _create_wrapped_model was called from _try_create_model_and_schema in func_metadata.py.
3. It was triggered because the scripts() tool's return type dict | list | str (a types.UnionType) fell outside both the GenericAlias and plain type branches, landing in the generic else branch that wraps the annotation as-is.

Comparing with Union[dict, list, str] (which is a GenericAlias and works fine) confirmed that only the Python 3.10+ | syntax triggers this path. The fix was then implemented and verified locally.

Error Trace

pydantic.errors.PydanticUserError: A non-annotated attribute was detected:
  `result = dict | list | str`.
All model fields require a type annotation; if `result` is not meant to be a field,
you may be able to resolve this error by annotating it as a `ClassVar` or
updating `model_config['ignored_types']`.

Root Cause

The call chain is:

1. inspect.signature(func, eval_str=True) resolves dict | list | str into a types.UnionType object (Python 3.10+).
2. In func_metadata.py:_try_create_model_and_schema, the UnionType is not a GenericAlias nor a plain type, so it falls into the else branch at line ~406.
3. _create_wrapped_model(model_name, result=annotation) is called.
4. Inside _create_wrapped_model, create_model(model_name, result=annotation) is called — Pydantic's create_model interprets result=dict | list | str as a bare default value (not a type annotation), because UnionType is not recognized as a field annotation in this context.

Proposed Fix

In _create_wrapped_model (file: src/mcp/server/fastmcp/utilities/func_metadata.py), change the create_model call to use the (type, default) tuple form, which explicitly tells Pydantic that the first element is a type annotation:

# Line ~483
- return create_model(model_name, result=annotation)
+ return create_model(model_name, result=(annotation, ...))

... (Ellipsis) means the field is required. This syntax works correctly with types.UnionType, GenericAlias, and all other annotation forms.

Workaround

If you cannot patch the library, avoid using Python 3.10+ union syntax in tool return types:

# Instead of:
async def my_tool(flag: bool) -> dict | list | str:

# Use typing.Union:
from typing import Union
async def my_tool(flag: bool) -> Union[dict, list, str]:

Union[dict, list, str] is a GenericAlias and is handled correctly by the existing code path.

---

Reported by: Ianwusb — discovered the bug while using FastMCP in a personal project, traced the error through the call stack, and identified the root cause with assistance from DeepSeek-V4-Pro analysis.

[jshaofa-ui]

Test comment

[jshaofa-ui]

Root Cause Analysis & Fix

The Bug

In src/mcp/server/mcpserver/utilities/func_metadata.py, the _create_wrapped_model function (line 481) passes the annotation directly to Pydantic's create_model(). When annotation is a Python 3.10+ types.UnionType (e.g., dict | list | str), Pydantic raises PydanticUserError because it expects typing.Union, not types.UnionType.

The Fix

Add a normalization step in _create_wrapped_model:

from types import UnionType
from typing import Union, get_args

def _create_wrapped_model(func_name: str, annotation: Any) -> type[BaseModel]:
    model_name = f"{func_name}Output"
    # Normalize Python 3.10+ union syntax (A | B | C) to typing.Union
    if isinstance(annotation, UnionType):
        annotation = Union[get_args(annotation)]
    return create_model(model_name, result=annotation)

Why This Works

• types.UnionType (from A | B) and typing.Union[A, B] are semantically identical
• Pydantic's create_model() handles typing.Union correctly
• This is a pure normalization — no behavioral change for existing code
• Minimal risk: only affects the specific case of Python 3.10+ union syntax