Tighten the public API surface: root exports, listen types, dead-code removal

Closed
MA
2mo ago
+186-205

Cleanup pass over the v2 public surface: a few missing exports, a few dead ones, and some no-op aliases.

Motivation and Context

  • Root mcp: exports MCPServer next to the existing Client, so from mcp import MCPServer, Client works (the first-steps.md tip claiming otherwise is removed). Also exports NoBackChannelError, which every server-initiated request path can raise on a 2026-07-28 connection. Drops the v1-carryover SamplingRole alias (use mcp.types.Role).
  • mcp.client: re-exports the types Client.listen() yields and raises — Subscription, SubscriptionLost, ListenNotSupportedError — which previously required reaching into mcp.client.subscriptions.
  • Dead surface removed: StreamableHTTPError / ResumptionError (never raised from a code path a caller could catch) and the unused StreamableHTTPTransport.get_session_id(); the no-op RegistrationRequest / TokenSuccessResponse auth-handler aliases; the validate_extension_identifier re-export alias in mcp.server.extension; the unreachable __main__ guard in mcp/cli/__init__.py.
  • The lowlevel server Context is not constructed by ServerRunner yet, so it moves to the private mcp.server._context module until it's wired back in.
  • _handle_resumption_request now takes the resumption token as a required argument instead of re-deriving it, which is what let the unreachable no-token branch (and the two exception classes) go away.
  • Enables ruff RUF022 and sorts every __all__; mcp_types/__init__.py is exempted since its __all__ is grouped by section comments on purpose.

How Has This Been Tested?

Full ./scripts/test (100% coverage held, strict-no-cover clean), plus a smoke test of the public boundary in a fresh interpreter: root/mcp.client imports resolve, removed names raise ImportError, and from mcp import MCPServer, Client round-trips a tool call both in-memory and over Streamable HTTP.

Breaking Changes

Yes, all documented in docs/migration.md: SamplingRole is gone from the root package, StreamableHTTPError/ResumptionError/get_session_id() are gone from mcp.client.streamable_http, and mcp.server.context.Context is now private (ServerRequestContext and the middleware types are unchanged).

Types of changes

  • Bug fix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to change)
  • Documentation update

Checklist

  • I have read the MCP Documentation
  • My code follows the repository's style guidelines
  • New and existing tests pass locally
  • I have added appropriate error handling
  • I have added or updated documentation as needed

Additional context

AI Disclaimer