Title: structuredContent for a TypedDict return injects nulls for NotRequired keys, violating the tool's own outputSchema · Issue #3224 · modelcontextprotocol/python-sdk · GitHub
Open Graph Title: structuredContent for a TypedDict return injects nulls for NotRequired keys, violating the tool's own outputSchema · Issue #3224 · modelcontextprotocol/python-sdk
X Title: structuredContent for a TypedDict return injects nulls for NotRequired keys, violating the tool's own outputSchema · Issue #3224 · modelcontextprotocol/python-sdk
Description: Release line 2.x (main), reproduced at a4f4ccd0. Bug description A tool whose return annotation is a TypedDict with NotRequired keys (or total=False) publishes an outputSchema in which those properties are non-nullable, but structuredCon...
Open Graph Description: Release line 2.x (main), reproduced at a4f4ccd0. Bug description A tool whose return annotation is a TypedDict with NotRequired keys (or total=False) publishes an outputSchema in which those proper...
X Description: Release line 2.x (main), reproduced at a4f4ccd0. Bug description A tool whose return annotation is a TypedDict with NotRequired keys (or total=False) publishes an outputSchema in which those proper...
Opengraph URL: https://github.com/modelcontextprotocol/python-sdk/issues/3224
X: @github
Domain: github.com
{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"structuredContent for a TypedDict return injects nulls for NotRequired keys, violating the tool's own outputSchema","articleBody":"### Release line\n\n2.x (`main`), reproduced at `a4f4ccd0`.\n\n### Bug description\n\nA tool whose return annotation is a `TypedDict` with `NotRequired` keys (or `total=False`)\npublishes an `outputSchema` in which those properties are **non-nullable**, but\n`structuredContent` materialises every key the tool did not return as an explicit `null`.\n\nThe response therefore violates the schema the same server just advertised, and a conforming\nclient rejects the call. The SDK's own client does exactly that, so these tools are effectively\nunusable — even though TypedDict is one of the return shapes structured output documents.\n\nThe unstructured text block and `structuredContent` also disagree, so a client that skips\nvalidation sees two different answers for the same call.\n\n### Steps to reproduce\n\n```python\nimport anyio, json\nfrom typing import NotRequired, TypedDict\nfrom mcp.server.mcpserver import MCPServer\nfrom mcp import Client\n\nclass Person(TypedDict):\n name: str\n age: NotRequired[int]\n nickname: NotRequired[str]\n\nmcp = MCPServer(\"td\")\n\n@mcp.tool()\ndef get_person() -> Person:\n return {\"name\": \"Dave\"} # omits both optional keys\n\nasync def main():\n async with Client(mcp) as c:\n tools = await c.list_tools()\n print(\"outputSchema:\", json.dumps(tools.tools[0].output_schema, sort_keys=True))\n r = await c.call_tool(\"get_person\", {})\n print(\"structuredContent:\", r.structured_content)\n\nanyio.run(main)\n```\n\n### Actual behaviour\n\n```\noutputSchema: {\"properties\": {\"age\": {\"default\": null, \"title\": \"Age\", \"type\": \"integer\"},\n \"name\": {\"title\": \"Name\", \"type\": \"string\"},\n \"nickname\": {\"default\": null, \"title\": \"Nickname\", \"type\": \"string\"}},\n \"required\": [\"name\"], \"title\": \"Person\", \"type\": \"object\"}\n\nRuntimeError: Invalid structured content returned by tool get_person: None is not of type 'string'\n\nFailed validating 'type' in schema['properties']['nickname']:\n {'default': None, 'title': 'Nickname', 'type': 'string'}\nOn instance['nickname']:\n None\n```\n\n`structuredContent` is `{\"name\": \"Dave\", \"age\": None, \"nickname\": None}` while the text block is\n`{\"name\": \"Dave\"}`.\n\n### Expected behaviour\n\n`structuredContent` is `{\"name\": \"Dave\"}` — a `NotRequired` key the tool omitted is absent, not\nnull — which validates against the published schema, and the call succeeds.\n\n### Root cause\n\n`_create_model_from_typeddict` (`src/mcp/server/mcpserver/utilities/func_metadata.py`) gives each\nnon-required key a `None` **default** to make it optional on the generated model; the declared type\nstays non-nullable, so the emitted schema is `{\"type\": \"integer\", \"default\": null}` and the key is\nabsent from `required`. `convert_result` then dumps with\n`model_dump(mode=\"json\", by_alias=True)` and no `exclude_unset`.\n\nThe file's own comment already prescribes the fix:\n\n```python\n# For optional TypedDict fields, set default=None\n# This makes them not required in the Pydantic model\n# The model should use exclude_unset=True when dumping to get TypedDict semantics\n```\n\nNothing applies it.\n\n### Why the tests do not catch it\n\n`tests/server/mcpserver/test_func_metadata.py::test_structured_output_typeddict` covers exactly\nthis shape but asserts only the schema, and marks the tool body `# pragma: no cover` — the tool is\nnever invoked, so `convert_result` is never exercised for a partial TypedDict.\n\n### Not a duplicate of #3100 / PR #3118\n\nThat pair concerns the validation-vs-serialization JSON-schema mode. `model_json_schema(mode=\"serialization\")`\nproduces byte-identical output for a `(int, None)` field, so it does not address this. Note #3118 does\nedit adjacent lines, so ordering matters if both land.\n\n### Disclosure\n\nInvestigated with AI assistance (Claude Code). I have a fix and tests ready and will open a PR\nlinked to this issue.\n","author":{"url":"https://github.com/sainikhiljuluri","@type":"Person","name":"sainikhiljuluri"},"datePublished":"2026-07-30T17:49:14Z","url":"https://github.com/modelcontextprotocol/python-sdk/issues/3224"}
| 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:d89499a3-f371-a31f-55d7-9c552e823687 |
| current-catalog-service-hash | 81bb79d38c15960b92d99bca9288a9108c7a47b18f2423d0f6438c5b7bcd2114 |
| request-id | DACA:25A204:9480B9:C5C937:6B00E23F |
| html-safe-nonce | e62ba59cd1c52f574ece9f6b5d82f9a3b8969169fb3fd4ba36d2a4174c0ade87 |
| visitor-payload | eyJyZWZlcnJlciI6IiIsInJlcXVlc3RfaWQiOiJEQUNBOjI1QTIwNDo5NDgwQjk6QzVDOTM3OjZCMDBFMjNGIiwidmlzaXRvcl9pZCI6Ijg5NDUwMDM5Mjk2MTIxMTY1NDMiLCJyZWdpb25fZWRnZSI6ImlhZCIsInJlZ2lvbl9yZW5kZXIiOiJpYWQifQ== |
| visitor-hmac | fb9a8592e573e955b67ca5ca0400469727cb546a9b244f3a95ee8d161aaedb0e |
| hovercard-subject-tag | issue:5022522063 |
| 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/3224/issue_layout |
| twitter:image | https://opengraph.githubassets.com/7bcea058bb0ba75ec343a5ac862687c7c8877a1a777083889f3f72f782b732a7/modelcontextprotocol/python-sdk/issues/3224 |
| twitter:card | summary_large_image |
| og:image | https://opengraph.githubassets.com/7bcea058bb0ba75ec343a5ac862687c7c8877a1a777083889f3f72f782b732a7/modelcontextprotocol/python-sdk/issues/3224 |
| og:image:alt | Release line 2.x (main), reproduced at a4f4ccd0. Bug description A tool whose return annotation is a TypedDict with NotRequired keys (or total=False) publishes an outputSchema in which those proper... |
| og:image:width | 1200 |
| og:image:height | 600 |
| og:site_name | GitHub |
| og:type | object |
| og:author:username | sainikhiljuluri |
| 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 | full |
| theme-color | #1e2327 |
| color-scheme | light dark |
| react-app-name | issues |
Links:
Viewport: width=device-width