Repository navigation
Bare dict / list / tuple return annotations silently produce no structured output #3725
Description
Initial Checks
- I confirm that I'm using the newest release of my line (the latest 2.x, or the latest 1.x if I'm still on v1)
- I confirm that I searched for my issue in https://github.com/modelcontextprotocol/python-sdk/issues before opening this issue
Release line
2.x (current stable)
Description
A tool annotated with a bare dict (or list / tuple) gets no outputSchema and no structuredContent. The result only arrives as JSON text. -> dict[str, Any] works, and -> str gets {"result": ...}. With structured_output=True the bare annotation raises InvalidSignature: Function f: return type <class 'dict'> is not serializable for structured output, which reads as if a dict weren't serializable.
Expected: -> dict behaves like dict[str, Any], and -> list / -> tuple like list[Any] (wrapped in {"result": ...}). Failing that, the structured-output docs could say that bare containers opt out.
Cause: _create_output_model sends bare dict / list / tuple to the "other class types" case. get_type_hints(dict) is empty, so the model stays None: the silent opt-out documented for classes without type hints, which isn't obvious for builtins. We hit it while building an MCP server: our tools were -> dict, and our client code expected structured_content that was always None.
Proposed fix: a case before the class fallback that sends bare dict down the dict[str, ...] path and wraps bare list / tuple like their generic forms, plus a test and one sentence in docs/servers/structured-output.md. It's about 10 lines of code, and the full suite passes (6206 passed). One behaviour change to weigh: existing bare -> dict / -> list tools would start publishing an outputSchema and validating their results.
I'd like to send this as a PR if you're open to it. It's on a branch: g-s-jithesh@6ecfa04
I used an AI coding assistant (Claude Code) to help investigate this and draft the fix. I reproduced the bug myself and reviewed the change.
Example Code
import asyncio
from typing import Any
from mcp import Client
from mcp.server.mcpserver import MCPServer
mcp = MCPServer("repro")
@mcp.tool()
def bare() -> dict:
return {"id": 1}
@mcp.tool()
def typed() -> dict[str, Any]:
return {"id": 1}
async def main() -> None:
async with Client(mcp) as client:
for name in ("bare", "typed"):
print(name, (await client.call_tool(name, {})).structured_content)
asyncio.run(main())
# bare None
# typed {'id': 1}Python & MCP Python SDK
Python 3.14, Windows 11; mcp 2.3.0, and main at 9f66f37 (src/mcp/server/mcpserver/utilities/func_metadata.py, _create_output_model)
Activity
xuilen commentedon Oct 17, 2026
I was able to reproduce this. In
_create_output_model(src/mcp/server/mcpserver/utilities/func_metadata.py), baredict,list,tuple, andsetfall through to the ordinary class inspection whereget_type_hints()returns{}, leavingoutput_modelasNone(or raisingInvalidSignaturewhenstructured_output=True).I've verified a minimal fix and test coverage locally:
dict(andtyping.Dict) asAnnotated[dict[str, Any], Field(title=f"{func_name}DictOutput")]without wrapping (matchingdict[str, Any]behavior).list,tuple,set,frozenset, andtyping.List) through_create_wrapped_modelwithwrap_output=True.All 642 existing mcpserver tests plus regression tests for all bare containers pass cleanly (
uv run pytest tests/server/mcpserver/), andruff check/ruff formatare clean.Happy to open a PR for this if this matches the intended design and you'd like to assign the issue.
(AI-assisted investigation & implementation)
g-s-jithesh commentedon Oct 17, 2026
Thanks for confirming the reproduction. Good catch on
set/frozenset: they take the same path, and I've added them to the branch with tests (all 642 tests intests/server/mcpserver/pass): main...g-s-jithesh:python-sdk:fix/bare-container-structured-outputtyping.Dict/typing.Listwithout parameters already produce structured output today (wrapped in{"result": ...}), so they aren't part of the silentNone. What's left is an inconsistency: a baretyping.Dictis wrapped whiledict/dict[str, Any]aren't. Changing that would alter existing output, so I've left it for maintainers to decide.As the reporter, I'd still like to send the PR from that branch if a maintainer is happy to assign this.
(Investigated and drafted with an AI coding assistant.)
xuilen commentedon Oct 17, 2026
Sounds great! Glad the
set/frozensetedge cases were helpful. Best of luck with the PR!