func_metadata raises uncaught PydanticSchemaGenerationError for Iterator/AsyncIterator tool return annotations instead of the unstructured fallback #3573

Confirmed on mcp 2.2.0 — all three registration shapes raise the raw pydantic.errors.PydanticSchemaGenerationError for collections.abc.Iterator[str] / AsyncIterator[str] returns (func_metadata(search), func_metadata(search, structured_output=True), and the Tool.from_function path).

The traceback pins exactly where the intended fallback is defeated. In mcp/server/mcpserver/utilities/func_metadata.py:

line 444, in func_metadata          -> output_model, wrap_output = _create_output_model(...)
line 518, in _create_output_model   -> model = _create_wrapped_model(func_name, original_annotation)
line 621, in _create_wrapped_model  -> create_model(... result: Iterator[str] ...)  # raises

Two things make this a straightforward fix:

1. The raise happens at L444, outside the guarded region. The try/except at L447-469 exists precisely to turn unsupported return types into a graceful outcome, and PydanticSchemaGenerationError (a PydanticUserError subclass on pydantic 2.13) is already covered conceptually by its caught types — but _create_output_model runs before the try, so _create_wrapped_model's create_model call escapes unprotected. Both intended behaviors are defeated by the same escape: the unstructured fallback (return FuncMetadata(arg_model=arguments_model), L477) and, for structured_output=True, the proper InvalidSignature (L471-475).

2. Iterator returns aren't recognized as content-iterators. The early-out at L437 (if structured_output is None and _returns_content(return_type_expr)) returns an unstructured FuncMetadata for annotations the model reads as content — but it doesn't match the PEP 484 generator spellings Iterator[...]/AsyncIterator[...], so they fall through into schema construction instead.

Wrapping the _create_output_model call in the existing except handling would restore both documented behaviors with one change; optionally treating Iterator/AsyncIterator origins in _returns_content would give generator tools the same unstructured default as content-block returns.

Reproduced this. Root cause: src/mcp/server/mcpserver/utilities/func_metadata.py:444 calls _create_output_model outside the try/except at lines 446-470 that reports unserializable return types at registration, so the PydanticSchemaGenerationError it raises for Iterator/AsyncIterator escapes func_metadata uncaught.

Minimal reproduction:

from typing import Iterator

from mcp.server.mcpserver.tools import Tool
from mcp.server.mcpserver.utilities.func_metadata import func_metadata


def search(n: int) -> Iterator[str]:
    yield from ["a"] * n


for label, call in [
    ("func_metadata(search)", lambda: func_metadata(search)),
    ("func_metadata(search, structured_output=True)", lambda: func_metadata(search, structured_output=True)),
    ("Tool.from_function(search)", lambda: Tool.from_function(search)),
]:
    try:
        call()
        print(f"{label}: OK")
    except Exception as e:
        print(f"{label}: UNCAUGHT {type(e).__module__}.{type(e).__name__}: {str(e)[:80]}")
# AsyncIterator[str] return annotations behave identically

Observed output:

func_metadata(search): UNCAUGHT pydantic.errors.PydanticSchemaGenerationError: Unable to generate pydantic-core schema for typing.Iterator[str]. Set `arbitrary
func_metadata(search, structured_output=True): UNCAUGHT pydantic.errors.PydanticSchemaGenerationError: Unable to generate pydantic-core schema for typing.Iterator[str]. Set `arbitrary
Tool.from_function(search): UNCAUGHT pydantic.errors.PydanticSchemaGenerationError: Unable to generate pydantic-core schema for typing.Iterator[str]. Set `arbitrary

Fix is ready on BlueX888:fix/prep-func-metadata-iterator-return-uncaught-pydantic-error (commit 2f4ce1ae). Moves the _create_output_model call inside that existing try/except, so Iterator/AsyncIterator returns follow the documented contract: no output schema by default, InvalidSignature with structured_output=True.
Verified with: uv run --frozen pytest tests/server/mcpserver/test_func_metadata.py

Happy to open the PR once you confirm the approach or assign this to me.

Confirmed on mcp 2.2.0 with the v2 API (MCPServer): both the default path and structured_output=True raise the raw PydanticSchemaGenerationError at registration for a -> Iterator[str] tool — the generator tool simply cannot be registered at all.

Minimal repro:

from mcp.server.mcpserver import MCPServer
from typing import Iterator

server = MCPServer("repro")

@server.tool()
def search(query: str) -> Iterator[str]:
    """Search things."""
    yield "a"

→ PydanticSchemaGenerationError: Unable to generate pydantic-core schema for typing.Iterator[str]. Same for structured_output=True.

The contract says the default should fall back to an unstructured tool (structured_output=None), and structured_output=True should raise the SDK's own InvalidSignature — a raw pydantic error escapes both. Root-cause candidate: func_metadata's return-type schema generation treats Iterator/AsyncIterator as a schema-able output type instead of short-circuiting to the generator/unstructured path first.

Happy to open a PR with a failing test first (both spellings must register without raising; structured_output=True must surface InvalidSignature) plus the narrow fix, if a maintainer assigns the issue — the repo's bot auto-closes non-assignee PRs, so I'm holding the branch until then.

Affiliation: we ship a 140-tool MCP server and hit this exact class of annotation edge case in our own tool registry.

Confirmed on Windows 11 / Python 3.13 / pydantic 2.12.5 against main (f1b6589) — all four spellings crash at registration, with both the default and structured_output=True:

from typing import Iterator
from mcp.server.mcpserver.utilities.func_metadata import func_metadata

def search(n: int) -> Iterator[str]:
    yield from ["a"] * n

func_metadata(search)   # pydantic.errors.PydanticSchemaGenerationError

The escape point matches @BlueX888's analysis: the _create_output_model() call (func_metadata.py:444 on main) sits outside the try at :446 that routes expected schema failures to the unstructured fallback, so the PydanticSchemaGenerationError raised by create_model(..., result=Iterator[str]) inside _create_wrapped_model() escapes func_metadata entirely.

The fix that keeps the existing semantics is to route that call through the same failure path: on PydanticSchemaGenerationError, degrade to the unstructured fallback (output_model=None), which also makes structured_output=True raise InvalidSignature via the existing check. Two notes from testing this locally:

• Both spellings need covering: typing.Iterator[str] (typing._GenericAlias) and collections.abc.Iterator[str] (types.GenericAlias) take different branches in _create_output_model but end at the same create_model crash.
• Generator[str, None, None] is unaffected: pydantic models it as a sequence, so it builds the wrapped {"result": [...]} schema today and keeps doing so after the fix.

I have this working locally with regression tests for all four spellings plus the Generator contrast — a PR is up at #3587 linking this issue.

Disclosure: this was developed with AI assistance; I have reviewed the diff and run the tests locally.