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

比較 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 表示趨於一致，或是針對有意保留的差異進行文件說明並提供遷移指引。

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