[v2] Allow MCPServer to disable subscriptions/listen

Initial Checks

• I confirm that I'm using the newest release of my line (the latest 2.x, or the latest 1.x if I'm still on v1)
• I confirm that I searched for my issue in https://github.com/modelcontextprotocol/python-sdk/issues before opening this issue

Release line

2.x (current stable)

Description

What happened?

MCPServer always installs a subscriptions/listen handler:

on_subscriptions_listen=ListenHandler(self._subscriptions)

The constructor exposes subscriptions: SubscriptionBus | None = None, but None creates an InMemorySubscriptionBus; it does not disable subscriptions.

This causes server/discover to advertise:

{
  "tools": {"listChanged": true},
  "prompts": {"listChanged": true},
  "resources": {"listChanged": true, "subscribe": true}
}

Our MCP server has a static catalog and never publishes change notifications. It runs as a stateless Streamable HTTP server on AWS Lambda.

Claude Code 2.1.235 automatically opened four subscriptions/listen streams during discovery. Each request followed the long-lived SSE path and held a Lambda invocation until timeout.

We currently reject these requests in ASGI middleware. This prevents the timeout, but the server still advertises subscription support, so clients continue attempting the requests.

The low-level Server supports disabling this correctly through:

Server(..., on_subscriptions_listen=None)

The high-level MCPServer has no equivalent public option. Removing the handler through _lowlevel_server._request_handlers works, but relies on private internals.

What did you expect?

MCPServer should provide a supported opt-out, for example:

MCPServer(..., subscriptions=False)

or:

MCPServer(..., enable_subscriptions=False)

When disabled:

• subscriptions/listen should not be registered.
• server/discover should advertise the relevant change and subscription capabilities as false.
• An unsolicited subscriptions/listen call should return Method not found.
• Existing behavior should remain the default for compatibility.
  This matches SEP-2575’s stateless-first, “pay as you go” design. Long-lived streams should only be enabled when the server uses them.

Area

Server

References

• SEP-2575
• Subscription implementation PR #3035
• Capabilities issue #2896

AI assistance disclosure: I used an AI coding assistant to inspect the SDK source and help draft this report. I reviewed and verified the contents.

Example Code

from mcp.server import MCPServer

server = MCPServer("static-server")

capabilities = server._lowlevel_server.get_capabilities(
    protocol_version="2026-07-28"
)

print(capabilities.model_dump(by_alias=True, exclude_none=True))

Python & MCP Python SDK

Python 3.11
mcp 2.0.0
AWS Lambda
Streamable HTTP
json_response=True
stateless_http=True

从 MCPServer 构造函数及其对 on_subscriptions_listen=ListenHandler(self._subscriptions) 的注册开始，然后检查 _lowlevel_server.get_capabilities 和 subscriptions/listen 请求路径。定义公开的 opt-out，同时保留当前的默认行为。完成的标准是：已禁用的服务器省略该 handler，将相关 capabilities 声明为 false，并对未经请求的 subscriptions/listen 调用返回 Method not found。