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

So sánh các luồng initialize và get_capabilities trong src/mcp/server/lowlevel/server.py, sau đó lần theo kiểu trong src/mcp-types/mcp_types/_types.py và việc xử lý phản hồi trong src/mcp/server/runner.py. Xem xét việc cung cấp cho client trong src/mcp/client/session.py và trường tùy chọn trong schema/2026-07-28.json. Được coi là hoàn tất khi hai biểu diễn discovery hợp nhất hoặc khi sự khác biệt có chủ đích được ghi lại kèm hướng dẫn di chuyển.

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