Public API for runtime handler registration/deregistration on low-level Server

[maxisbey]

Summary

The low-level Server class has a private _add_request_handler() method but no public API for adding or removing request/notification handlers at runtime. The only supported way to register handlers is via on_* constructor kwargs, which means all handlers must be known at construction time.

This is limiting for frameworks and advanced use cases that need to:

• Register handlers for protocol extensions or custom methods after server construction
• Remove or replace handlers dynamically (e.g., feature flags, hot-reloading, test fixtures)
• Register notification handlers post-construction (currently no mutation API at all for _notification_handlers)

Current state

• _add_request_handler() exists but is private. It silently replaces existing handlers.
• _has_handler() is also private.
• There is no remove/deregister method for either request or notification handlers.
• MCPServer.completion() already uses _add_request_handler() with a pyright: ignore[reportPrivateUsage] suppression and a TODO acknowledging this needs a better pattern.

Proposal

Make handler registration/deregistration a first-class public API on the low-level Server:

server.add_request_handler(method: str, handler: Callable) -> None
server.remove_request_handler(method: str) -> None
server.add_notification_handler(method: str, handler: Callable) -> None
server.remove_notification_handler(method: str) -> None
server.has_handler(method: str) -> bool

Related issues

• Support custom method handlers with custom params and return types on MCPServer #2105 — Custom method handlers on MCPServer (higher-level, different scope)
• Define and document the public Python SDK API surface #1701 — Public API audit
• Middleware Support in MCP #1233 — Middleware support (may interact with handler registration)

_{AI Disclaimer}