[v2] MCPServer reports empty experimental capabilities as {} via initialize but None via server/discover

Compare the initialize and get_capabilities paths in src/mcp/server/lowlevel/server.py, then trace the type in src/mcp-types/mcp_types/_types.py and response handling in src/mcp/server/runner.py. Review the client exposure in src/mcp/client/session.py and the optional field in schema/2026-07-28.json. Done means the two discovery representations converge or the intentional difference is documented with migration guidance.

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/discover: capabilities.experimental is None; the field is omitted on the wire, while the parsed SDK model materializes None

In 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.

This 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.

Minimal reproduction

from mcp.server.lowlevel import Server

server = Server("repro", version="0.0.0")
legacy = server.create_initialization_options().capabilities
modern = server.get_capabilities(protocol_version="2026-07-28")

for name, capabilities in (("legacy", legacy), ("modern", modern)):
    wire = capabilities.model_dump(by_alias=True, mode="json", exclude_none=True)
    print(name, capabilities.experimental, "experimental" in wire)

Observed with Python 3.14.3, mcp==2.0.0, mcp-types==2.0.0, and Pydantic 2.13.4:

legacy {} True
modern None False

Expected behavior

The 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.

Source diagnosis

The tagged v2.0.0 source appears to explain the mismatch:

• 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
• get_capabilities preserves None: https://github.com/modelcontextprotocol/python-sdk/blob/6f69a3758ebf2ee55ce050f58b470ce11af71133/src/mcp/server/lowlevel/server.py#L555-L625
• 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
• The type defaults experimental to None: https://github.com/modelcontextprotocol/python-sdk/blob/6f69a3758ebf2ee55ce050f58b470ce11af71133/src/mcp-types/mcp_types/_types.py#L485-L489
• The runner omits None from the modern wire response: https://github.com/modelcontextprotocol/python-sdk/blob/6f69a3758ebf2ee55ce050f58b470ce11af71133/src/mcp/server/runner.py#L110-L123
• 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
• 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

Downstream impact and revisit condition

A 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.

Version

• Python: 3.14.3
• MCP Python SDK: 2.0.0
• mcp-types: 2.0.0
• Pydantic: 2.13.4
• OS: Windows