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

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

比较 src/mcp/server/lowlevel/server.py 中的 initialize 和 get_capabilities 路径，然后跟踪 src/mcp-types/mcp_types/_types.py 中的类型以及 src/mcp/server/runner.py 中的响应处理。检查 src/mcp/client/session.py 中客户端的暴露方式，以及 schema/2026-07-28.json 中的可选字段。完成的标准是两个 discovery 表示趋于一致，或者对有意保留的差异进行文档说明并提供迁移指南。