Title: Recursive tool return type publishes an outputSchema with no root type, failing tools/list on 2025-11-25 sessions · Issue #3337 · modelcontextprotocol/python-sdk · GitHub
Open Graph Title: Recursive tool return type publishes an outputSchema with no root type, failing tools/list on 2025-11-25 sessions · Issue #3337 · modelcontextprotocol/python-sdk
X Title: Recursive tool return type publishes an outputSchema with no root type, failing tools/list on 2025-11-25 sessions · Issue #3337 · modelcontextprotocol/python-sdk
Description: Release line 2.x (main), observed at b2025ab and on #3331. Bug description When an MCPServer tool's return type is self-referential, pydantic emits the output schema as {"$defs": {...}, "$ref": "#/$defs/Node"} with no root "type": "objec...
Open Graph Description: Release line 2.x (main), observed at b2025ab and on #3331. Bug description When an MCPServer tool's return type is self-referential, pydantic emits the output schema as {"$defs": {...}, "$ref": "#/...
X Description: Release line 2.x (main), observed at b2025ab and on #3331. Bug description When an MCPServer tool's return type is self-referential, pydantic emits the output schema as {"$defs": {......
Opengraph URL: https://github.com/modelcontextprotocol/python-sdk/issues/3337
X: @github
Domain: github.com
{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"Recursive tool return type publishes an outputSchema with no root type, failing tools/list on 2025-11-25 sessions","articleBody":"### Release line\n\n2.x (`main`), observed at b2025ab8 and on #3331.\n\n### Bug description\n\nWhen an MCPServer tool's return type is self-referential, pydantic emits the output schema as `{\"$defs\": {...}, \"$ref\": \"#/$defs/Node\"}` with no root `\"type\": \"object\"`. That's fine on 2026-07-28 sessions, but the 2025-11-25 `Tool.outputSchema` shape requires `type: \"object\"` at the root, so serializing the `tools/list` result for a legacy-negotiated client fails validation and the client gets an error for the **entire listing**, not just that tool.\n\nOn `main` this affects recursive `BaseModel` return types. #3331 hands `TypedDict` returns to pydantic natively, so recursive `TypedDict`s join them (previously the hand-built mirror model happened to inline the root).\n\n### Steps to reproduce\n\n```python\nimport anyio\nfrom pydantic import BaseModel\nfrom mcp import Client\nfrom mcp.server.mcpserver import MCPServer\n\nclass Node(BaseModel):\n name: str\n children: list[\"Node\"] = []\n\nmcp = MCPServer(\"rec\")\n\n@mcp.tool()\ndef tree() -> Node:\n return Node(name=\"root\")\n\n@mcp.tool()\ndef other() -> int:\n return 1\n\nasync def main():\n async with Client(mcp) as c: # 2026-07-28\n print(sorted((await c.list_tools()).tools[1].output_schema)) # ['$defs', '$ref']\n async with Client(mcp, mode=\"legacy\") as c: # 2025-11-25\n await c.list_tools() # raises; server logs \"handler for 'tools/list' returned an invalid result\"\n\nanyio.run(main)\n```\n\nServer log on the legacy session:\n\n```\nValidationError: 1 validation error for ListToolsResult\ntools.0.outputSchema.type\n Field required [type=missing, input_value={'$defs': {'Node': {...}}, '$ref': '#/$defs/Node'}, input_type=dict]\n```\n\n### Expected behaviour\n\n`tools/list` succeeds on both protocol versions; the recursive tool's schema has an object root (e.g. inline the root `$ref`, or wrap it as `{\"type\": \"object\", \"allOf\": [{\"$ref\": ...}], \"$defs\": ...}`).\n\nSeparately, it seems worth deciding whether one tool's unrepresentable schema should fail the whole listing on a legacy session or just drop/degrade that tool.\n\n\u003csub>[AI Disclaimer](https://gist.github.com/maxisbey/6123d132484e4c533eab519a2800693d)\u003c/sub>\n","author":{"url":"https://github.com/maxisbey","@type":"Person","name":"maxisbey"},"datePublished":"2026-08-19T16:11:34Z","url":"https://github.com/modelcontextprotocol/python-sdk/issues/3337"}
| react-profiling | 0 |
| react-import-map | react,react-dom,react-dom/client,react-dom/profiling,react-is,react/compiler-runtime,react/jsx-dev-runtime,react/jsx-runtime,scheduler@b8488ee2c322 |
| route-pattern | /_view_fragments/issues/show/:user_id/:repository/:id/issue_layout(.:format) |
| route-controller | voltron_issues_fragments |
| route-action | issue_layout |
| fetch-nonce | v2:fe2a42dd-205c-ea1b-c350-cb9697f202d6 |
| current-catalog-service-hash | 81bb79d38c15960b92d99bca9288a9108c7a47b18f2423d0f6438c5b7bcd2114 |
| request-id | BFD6:31B4CC:9ED608:D2B7F6:6B00E4DA |
| html-safe-nonce | 931a8979213c37e71947f81598d0567bf94a91ef6a3b20643699b26912a05ed7 |
| visitor-payload | eyJyZWZlcnJlciI6IiIsInJlcXVlc3RfaWQiOiJCRkQ2OjMxQjRDQzo5RUQ2MDg6RDJCN0Y2OjZCMDBFNERBIiwidmlzaXRvcl9pZCI6IjMxODMzMzU5ODA5Nzk1MTI1MzgiLCJyZWdpb25fZWRnZSI6ImlhZCIsInJlZ2lvbl9yZW5kZXIiOiJpYWQifQ== |
| visitor-hmac | 287a316df106e431dffaa939d92dd1e0d1500206e3c0004f9c48867c26c2f470 |
| hovercard-subject-tag | issue:5194736439 |
| github-keyboard-shortcuts | repository,issues,copilot |
| google-site-verification | Apib7-x98H0j5cPqHWwSMm6dNU4GmODRoqxLiDzdx9I |
| octolytics-url | https://collector.github.com/github/collect |
| analytics-location | / |
| fb:app_id | 1401488693436528 |
| apple-itunes-app | app-id=1477376905, app-argument=https://github.com/_view_fragments/issues/show/modelcontextprotocol/python-sdk/3337/issue_layout |
| twitter:image | https://opengraph.githubassets.com/8ed99109da93e664f894e8cf94249b63775408ac394efcdb9fcf76a00247e3e3/modelcontextprotocol/python-sdk/issues/3337 |
| twitter:card | summary_large_image |
| og:image | https://opengraph.githubassets.com/8ed99109da93e664f894e8cf94249b63775408ac394efcdb9fcf76a00247e3e3/modelcontextprotocol/python-sdk/issues/3337 |
| og:image:alt | Release line 2.x (main), observed at b2025ab and on #3331. Bug description When an MCPServer tool's return type is self-referential, pydantic emits the output schema as {"$defs": {...}, "$ref": "#/... |
| og:image:width | 1200 |
| og:image:height | 600 |
| og:site_name | GitHub |
| og:type | object |
| og:author:username | maxisbey |
| hostname | github.com |
| expected-hostname | github.com |
| None | 27088b6977484d0d3321d9a11c907c6d6637b315cfa359ef7952dbf6292f9b14 |
| turbo-cache-control | no-preview |
| go-import | github.com/modelcontextprotocol/python-sdk git https://github.com/modelcontextprotocol/python-sdk.git |
| octolytics-dimension-user_id | 182288589 |
| octolytics-dimension-user_login | modelcontextprotocol |
| octolytics-dimension-repository_id | 862584018 |
| octolytics-dimension-repository_nwo | modelcontextprotocol/python-sdk |
| octolytics-dimension-repository_public | true |
| octolytics-dimension-repository_is_fork | false |
| octolytics-dimension-repository_network_root_id | 862584018 |
| octolytics-dimension-repository_network_root_nwo | modelcontextprotocol/python-sdk |
| turbo-body-classes | logged-out env-production page-responsive |
| disable-turbo | false |
| browser-stats-url | https://api.github.com/_private/browser/stats |
| browser-errors-url | https://api.github.com/_private/browser/errors |
| release | 624179fb8b88d26ba5bba08894eb60a1c5a1d93d |
| ui-target | canary-2 |
| theme-color | #1e2327 |
| color-scheme | light dark |
| react-app-name | issues |
Links:
Viewport: width=device-width