Title: NotRequired TypedDict return annotation raises PydanticForbiddenQualifier at tool registration on Python 3.10 · Issue #3227 · modelcontextprotocol/python-sdk · GitHub
Open Graph Title: NotRequired TypedDict return annotation raises PydanticForbiddenQualifier at tool registration on Python 3.10 · Issue #3227 · modelcontextprotocol/python-sdk
X Title: NotRequired TypedDict return annotation raises PydanticForbiddenQualifier at tool registration on Python 3.10 · Issue #3227 · modelcontextprotocol/python-sdk
Description: Release line 2.x (main), reproduced at a4f4ccd0. Bug description On Python 3.10 a tool whose return annotation is a TypedDict containing a NotRequired key cannot be registered at all. @mcp.tool() raises while the decorator runs, so the f...
Open Graph Description: Release line 2.x (main), reproduced at a4f4ccd0. Bug description On Python 3.10 a tool whose return annotation is a TypedDict containing a NotRequired key cannot be registered at all. @mcp.tool() r...
X Description: Release line 2.x (main), reproduced at a4f4ccd0. Bug description On Python 3.10 a tool whose return annotation is a TypedDict containing a NotRequired key cannot be registered at all. @mcp.tool() r...
Opengraph URL: https://github.com/modelcontextprotocol/python-sdk/issues/3227
X: @github
Domain: github.com
{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"NotRequired TypedDict return annotation raises PydanticForbiddenQualifier at tool registration on Python 3.10","articleBody":"### Release line\n\n2.x (`main`), reproduced at `a4f4ccd0`.\n\n### Bug description\n\nOn Python 3.10 a tool whose return annotation is a `TypedDict` containing a `NotRequired` key\ncannot be registered at all. `@mcp.tool()` raises while the decorator runs, so the failure lands at\nimport time and the tool never exists.\n\n3.11 and above are unaffected. The project supports 3.10 (`requires-python = \">=3.10\"`, and CI runs\na full 3.10 matrix), and `TypedDict` is one of the documented structured-output return shapes, so on\nthat interpreter the documented feature is unusable.\n\n### Steps to reproduce\n\n```python\nimport sys\nfrom typing_extensions import NotRequired, TypedDict\nfrom mcp.server.mcpserver import MCPServer\n\nclass Person(TypedDict):\n name: str\n age: NotRequired[int]\n\nmcp = MCPServer(\"td\")\nprint(\"python\", sys.version.split()[0])\n\n@mcp.tool()\ndef get_person() -> Person:\n return {\"name\": \"Dave\"}\n```\n\n```bash\nuv run --python 3.10 --frozen --all-extras --dev python repro.py\n```\n\n### Actual behaviour\n\n```\npython 3.10.19\npydantic.errors.PydanticForbiddenQualifier: The annotation 'NotRequired[int]' contains the\n'typing.NotRequired' type qualifier, which is invalid in the context it is defined.\n```\n\nThe same file on 3.13 registers the tool without complaint.\n\n### Expected behaviour\n\nThe tool registers on every supported interpreter, as it already does on 3.11+.\n\n### Root cause\n\n`_create_model_from_typeddict` (`src/mcp/server/mcpserver/utilities/func_metadata.py`) resolves the\nannotations with `typing.get_type_hints` and passes each one straight to `create_model`:\n\n```python\ntype_hints = get_type_hints(td_type)\n...\nmodel_fields[field_name] = (field_type, None)\n```\n\n`typing.get_type_hints` only strips the `Required` / `NotRequired` qualifier from 3.11 onwards.\nBelow that `field_type` is still `NotRequired[int]`, and pydantic rejects a bare qualifier outside a\nTypedDict context.\n\nObserved directly:\n\n```\npython 3.10.19 typing.get_type_hints(Person) -> {'name': str, 'age': typing_extensions.NotRequired[int]}\npython 3.13.12 typing.get_type_hints(Person) -> {'name': str, 'age': int}\n```\n\n`typing_extensions.get_type_hints` returns the stripped form on both.\n\n### Why the tests do not catch it\n\n`test_structured_output_typeddict` uses all-required keys, and the `total=False` variants express\noptionality through `__optional_keys__` rather than a qualifier in the annotation, so no existing\ntest constructs a `NotRequired[...]` annotation.\n\n### Note\n\nA fix is already included in #3225, because the tests added there cannot pass on 3.10 without it.\nFiling separately since the defect is independent of that PR's subject and is worth tracking on its\nown — happy to split the fix out into its own PR if you would prefer.\n\n### Disclosure\n\nInvestigated with AI assistance (Claude Code). Filed by me as the human contributor.\n","author":{"url":"https://github.com/sainikhiljuluri","@type":"Person","name":"sainikhiljuluri"},"datePublished":"2026-07-30T20:43:07Z","url":"https://github.com/modelcontextprotocol/python-sdk/issues/3227"}
| 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:e3f4a49f-8607-380c-bab8-9d71e27db17a |
| current-catalog-service-hash | 81bb79d38c15960b92d99bca9288a9108c7a47b18f2423d0f6438c5b7bcd2114 |
| request-id | D940:3F8AB1:A3DC36:D421C4:6B00E24C |
| html-safe-nonce | 4d85cb2cbc9dfe688d4eebb80b2539ce7571fd10936ef568e7e8c7aa3c5b18a4 |
| visitor-payload | eyJyZWZlcnJlciI6IiIsInJlcXVlc3RfaWQiOiJEOTQwOjNGOEFCMTpBM0RDMzY6RDQyMUM0OjZCMDBFMjRDIiwidmlzaXRvcl9pZCI6IjQ1MTU5MTI5NTI1MTA5OTcwNjgiLCJyZWdpb25fZWRnZSI6ImlhZCIsInJlZ2lvbl9yZW5kZXIiOiJpYWQifQ== |
| visitor-hmac | b2d3e34492fbd67fcbf90c644313ee25e137f24ea51d417cc153165339400645 |
| hovercard-subject-tag | issue:5023830041 |
| 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/3227/issue_layout |
| twitter:image | https://opengraph.githubassets.com/1de6a24625177609445c87a72cfa49fa93132501c30e0ca9f87ef56ac1f9d607/modelcontextprotocol/python-sdk/issues/3227 |
| twitter:card | summary_large_image |
| og:image | https://opengraph.githubassets.com/1de6a24625177609445c87a72cfa49fa93132501c30e0ca9f87ef56ac1f9d607/modelcontextprotocol/python-sdk/issues/3227 |
| og:image:alt | Release line 2.x (main), reproduced at a4f4ccd0. Bug description On Python 3.10 a tool whose return annotation is a TypedDict containing a NotRequired key cannot be registered at all. @mcp.tool() r... |
| 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