Title: [v2] MCPServer reports empty experimental capabilities as {} via initialize but None via server/discover · Issue #3254 · modelcontextprotocol/python-sdk · GitHub
Open Graph Title: [v2] MCPServer reports empty experimental capabilities as {} via initialize but None via server/discover · Issue #3254 · modelcontextprotocol/python-sdk
X Title: [v2] MCPServer reports empty experimental capabilities as {} via initialize but None via server/discover · Issue #3254 · modelcontextprotocol/python-sdk
Description: Description With mcp==2.0.0, the same unconfigured server exposes empty experimental capabilities differently through its two public discovery paths: initialize: capabilities.experimental == {} and the field is present on the wire server...
Open Graph Description: Description With mcp==2.0.0, the same unconfigured server exposes empty experimental capabilities differently through its two public discovery paths: initialize: capabilities.experimental == {} and...
X Description: Description With mcp==2.0.0, the same unconfigured server exposes empty experimental capabilities differently through its two public discovery paths: initialize: capabilities.experimental == {} and...
Opengraph URL: https://github.com/modelcontextprotocol/python-sdk/issues/3254
X: @github
Domain: github.com
{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"[v2] MCPServer reports empty experimental capabilities as {} via initialize but None via server/discover","articleBody":"### Description\n\nWith `mcp==2.0.0`, the same unconfigured server exposes empty experimental capabilities differently through its two public discovery paths:\n\n- initialize: `capabilities.experimental == {}` and the field is present on the wire\n- `server/discover`: `capabilities.experimental is None`; the field is omitted on the wire, while the parsed SDK model materializes `None`\n\nIn a sanitized capture this is visible at both `$.handshake.capabilities.experimental` and `$.handshake.result.capabilities.experimental` as `{}` to `null`. The `null` is a diagnostic model dump, not a literal modern wire value.\n\nThis distinction is client-visible. Code using `.get(...)` on the legacy value works but raises on the modern value, while checks such as `is not None` also change meaning.\n\n### Minimal reproduction\n\n```python\nfrom mcp.server.lowlevel import Server\n\nserver = Server(\"repro\", version=\"0.0.0\")\nlegacy = server.create_initialization_options().capabilities\nmodern = server.get_capabilities(protocol_version=\"2026-07-28\")\n\nfor name, capabilities in ((\"legacy\", legacy), (\"modern\", modern)):\n wire = capabilities.model_dump(by_alias=True, mode=\"json\", exclude_none=True)\n print(name, capabilities.experimental, \"experimental\" in wire)\n```\n\nObserved with Python 3.14.3, `mcp==2.0.0`, `mcp-types==2.0.0`, and Pydantic 2.13.4:\n\n```text\nlegacy {} True\nmodern None False\n```\n\n### Expected behavior\n\nThe two supported discovery paths should expose consistent public SDK semantics for an unconfigured experimental capability map, or the intentional difference should be documented with migration guidance.\n\n### Source diagnosis\n\nThe tagged v2.0.0 source appears to explain the mismatch:\n\n- The initialize path converts a missing experimental map to `{}`: https://github.com/modelcontextprotocol/python-sdk/blob/6f69a3758ebf2ee55ce050f58b470ce11af71133/src/mcp/server/lowlevel/server.py#L527-L548\n- `get_capabilities` preserves `None`: https://github.com/modelcontextprotocol/python-sdk/blob/6f69a3758ebf2ee55ce050f58b470ce11af71133/src/mcp/server/lowlevel/server.py#L555-L625\n- The modern discover handler calls it without an experimental map: https://github.com/modelcontextprotocol/python-sdk/blob/6f69a3758ebf2ee55ce050f58b470ce11af71133/src/mcp/server/lowlevel/server.py#L660-L675\n- The type defaults `experimental` to `None`: https://github.com/modelcontextprotocol/python-sdk/blob/6f69a3758ebf2ee55ce050f58b470ce11af71133/src/mcp-types/mcp_types/_types.py#L485-L489\n- The runner omits `None` from the modern wire response: https://github.com/modelcontextprotocol/python-sdk/blob/6f69a3758ebf2ee55ce050f58b470ce11af71133/src/mcp/server/runner.py#L110-L123\n- The client exposes the parsed discover capabilities: https://github.com/modelcontextprotocol/python-sdk/blob/6f69a3758ebf2ee55ce050f58b470ce11af71133/src/mcp/client/session.py#L719-L755 and https://github.com/modelcontextprotocol/python-sdk/blob/6f69a3758ebf2ee55ce050f58b470ce11af71133/src/mcp/client/session.py#L791-L797\n- The protocol schema makes the field optional and object-valued: https://github.com/modelcontextprotocol/python-sdk/blob/6f69a3758ebf2ee55ce050f58b470ce11af71133/schema/2026-07-28.json#L3117-L3177\n\n### Downstream impact and revisit condition\n\nA migration gate currently needs a provisional expected delta for this client-visible transition. We will retest the first 2.x release that fixes or documents this behavior and remove or revise that delta when the two representations converge or the intended contract is clarified.\n\n### Version\n\n- Python: 3.14.3\n- MCP Python SDK: 2.0.0\n- mcp-types: 2.0.0\n- Pydantic: 2.13.4\n- OS: Windows\r\n","author":{"url":"https://github.com/squibloads","@type":"Person","name":"squibloads"},"datePublished":"2026-08-05T07:00:12Z","url":"https://github.com/modelcontextprotocol/python-sdk/issues/3254"}
| 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:c60e80ec-0d05-1fbf-151a-151f4e316ab4 |
| current-catalog-service-hash | 81bb79d38c15960b92d99bca9288a9108c7a47b18f2423d0f6438c5b7bcd2114 |
| request-id | 81D8:16EED3:127AA3E:178A4D6:6B012187 |
| html-safe-nonce | 41345da001d8d0abf57a6bbcf9381d8f111a387a21a17b4ae8afe976365c0569 |
| visitor-payload | eyJyZWZlcnJlciI6IiIsInJlcXVlc3RfaWQiOiI4MUQ4OjE2RUVEMzoxMjdBQTNFOjE3OEE0RDY6NkIwMTIxODciLCJ2aXNpdG9yX2lkIjoiODg3Njk4NjUwODIzMDMzNjkwMyIsInJlZ2lvbl9lZGdlIjoiaWFkIiwicmVnaW9uX3JlbmRlciI6ImlhZCJ9 |
| visitor-hmac | 49e8857f8f3fd3048adf65565a7cee866ca7b3a125c0dddffdeb1d633b6bcde4 |
| hovercard-subject-tag | issue:5068257496 |
| 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/3254/issue_layout |
| twitter:image | https://opengraph.githubassets.com/4ea6788a45522245c0b57b5e90ee4e0fe6a54d7c71551d28ec836ceb534dd30d/modelcontextprotocol/python-sdk/issues/3254 |
| twitter:card | summary_large_image |
| og:image | https://opengraph.githubassets.com/4ea6788a45522245c0b57b5e90ee4e0fe6a54d7c71551d28ec836ceb534dd30d/modelcontextprotocol/python-sdk/issues/3254 |
| og:image:alt | Description With mcp==2.0.0, the same unconfigured server exposes empty experimental capabilities differently through its two public discovery paths: initialize: capabilities.experimental == {} and... |
| og:image:width | 1200 |
| og:image:height | 600 |
| og:site_name | GitHub |
| og:type | object |
| og:author:username | squibloads |
| hostname | github.com |
| expected-hostname | github.com |
| None | cc5dfdd32f62ebd3223cab3af3aa2b268d3605218237326a48a99d1efd89495c |
| 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 | 8c77c9e8439031ad54c75a250694842892f693e1 |
| ui-target | full |
| theme-color | #1e2327 |
| color-scheme | light dark |
| react-app-name | issues |
Links:
Viewport: width=device-width