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

Root `mcp` package: export `MCPServer` (alongside the existing `Client`,
so `from mcp import MCPServer, Client` works) and `NoBackChannelError`;
drop the v1-carryover `SamplingRole` alias (`mcp.types.Role`). `mcp.client`
now re-exports the types `Client.listen()` yields and raises: `Subscription`,
`SubscriptionLost`, `ListenNotSupportedError`.

Remove dead surface: `StreamableHTTPError`/`ResumptionError` (never raised
from a reachable path) and `StreamableHTTPTransport.get_session_id()` on the
client transport; the no-op `RegistrationRequest`/`TokenSuccessResponse`
auth-handler aliases; the `validate_extension_identifier` re-export alias;
the unreachable `__main__` guard in `mcp/cli/__init__.py`. The unused
lowlevel server `Context` moves to the private `mcp.server._context`
module.

`_handle_resumption_request` now takes the resumption token as a required
argument instead of re-deriving it and carrying an unreachable no-token
branch.

Enable ruff `RUF022` and sort every `__all__`; `mcp_types/__init__.py` is
exempted since its `__all__` is grouped by section comments on purpose.

Author: maxisbey

docs/get-started/first-steps.md

@@ -46,10 +46,6 @@ Three plain functions, three decorators. Each decorator is the entire registrati
 
 Everything else (the name, the description, the argument schema) the SDK reads from the function itself: its name, its docstring, its type hints. You never declared any of it separately.
 
-!!! tip
-    The two halves of the SDK have two import paths: `from mcp import Client` and
-    `from mcp.server import MCPServer`. There is no `from mcp import MCPServer`.
-
 ### Try it
 
 Run it with the MCP Inspector:

docs/migration.md

@@ -265,6 +265,7 @@ The following type aliases and classes have been removed from the protocol types
 | `AnyFunction` | Use `Callable[..., Any]` directly |
 | `ClientRequestType`, `ClientNotificationType`, `ClientResultType`, `ServerRequestType`, `ServerNotificationType`, `ServerResultType` | The union is now the bare name: `ClientRequest`, `ClientNotification`, `ClientResult`, `ServerRequest`, `ServerNotification`, `ServerResult` |
 | `TaskExecutionMode`, `TASK_FORBIDDEN`, `TASK_OPTIONAL`, `TASK_REQUIRED`, `TASK_STATUS_*` | Use string literals; `TaskStatus` remains as the literal-union type |
+| `SamplingRole` (a top-level `mcp` alias for `Role`, never a `mcp.types` name) | `mcp.types.Role` |
 
 **Before (v1):**
 
@@ -657,6 +658,8 @@ from mcp.server.mcpserver import MCPServer, Context
 mcp = MCPServer("Demo")
 ```
 
+`MCPServer` is also exported from the top-level `mcp` package, next to `Client` (`from mcp import MCPServer, Client`); `mcp.server` and `mcp.server.mcpserver` keep working as import paths.
+
 `Context` is the type annotation for the `ctx` parameter injected into tools, resources, and prompts (see [`get_context()` removed](#mcpserverget_context-removed) below). The `ctx.fastmcp` property is now `ctx.mcp_server`.
 
 All submodules under `mcp.server.fastmcp.*` are now under `mcp.server.mcpserver.*` with the same structure. Common imports:
@@ -2166,6 +2169,12 @@ The `headers`, `timeout`, `sse_read_timeout`, and `auth` parameters have been re
 
 `sse_client` is unchanged apart from the `httpx2` retyping: it still takes `url`, `headers`, `timeout`, `sse_read_timeout`, `httpx_client_factory` (which must now return an `httpx2.AsyncClient`), `auth` (now `httpx2.Auth | None`), and `on_session_created`. Only the streamable HTTP transport dropped its transport-level parameters; `StreamableHTTPTransport(url)` now takes just the URL.
 
+### `StreamableHTTPError`, `ResumptionError`, and `StreamableHTTPTransport.get_session_id()` removed
+
+`mcp.client.streamable_http` no longer defines `StreamableHTTPError` or its `ResumptionError` subclass: the transport never raised either from a code path a caller could catch, so `from mcp.client.streamable_http import StreamableHTTPError, ResumptionError` now raises `ImportError`. Transport failures surface as per-request JSON-RPC errors (see [Streamable HTTP: non-2xx responses now surface as per-request JSON-RPC errors](#streamable-http-non-2xx-responses-now-surface-as-per-request-json-rpc-errors)) or as the underlying `httpx2` exception; catch those instead.
+
+The unused `StreamableHTTPTransport.get_session_id()` method is gone as well; read the `session_id` attribute directly (or capture the header, as in [`get_session_id` callback removed](#get_session_id-callback-removed-from-streamable_http_client) above).
+
 ### `StreamableHTTPTransport.protocol_version` attribute removed
 
 The transport no longer holds per-connection protocol state; era-dependent headers (e.g. `MCP-Protocol-Version`) are now supplied per-message by the session. If you were reading `transport.protocol_version` to learn the negotiated version, read `session.protocol_version` (or `client.protocol_version` on the high-level `Client`) instead.
@@ -2771,7 +2780,7 @@ The user-facing methods for these features now carry `typing_extensions.deprecat
 
 - Sampling: `ServerSession.create_message()`, `ClientPeer.sample()`
 - Roots: `ServerSession.list_roots()`, `ClientPeer.list_roots()`, `ClientSession.send_roots_list_changed()`, `Client.send_roots_list_changed()`
-- Logging: `ServerSession.send_log_message()`, `Connection.log()`, `ClientSession.set_logging_level()`, `Client.set_logging_level()`, `mcp.server.context.Context.log()` (the lowlevel `Context`), and the `MCPServer` `Context` helpers `log()`, `debug()`, `info()`, `warning()`, `error()`
+- Logging: `ServerSession.send_log_message()`, `Connection.log()`, `ClientSession.set_logging_level()`, `Client.set_logging_level()`, and the `MCPServer` `Context` helpers `log()`, `debug()`, `info()`, `warning()`, `error()`
 
 Registering a handler for a deprecated capability is deprecated too. The `Server.__init__` parameters `on_set_logging_level` (Logging) and `on_roots_list_changed` (Roots) are now split out into a `typing_extensions.deprecated` overload, so passing either is flagged by type checkers and emits `mcp.MCPDeprecationWarning` at construction time. `on_progress` follows the same pattern (see below). The non-deprecated overload omits these parameters, so the common case stays warning-free.
 
@@ -2804,7 +2813,7 @@ rest of this guide stays focused on the v1-to-v2 upgrade itself.
 
 The 2026-07-28 protocol has no server-initiated requests, so a handler that reaches back to the client mid-request — `ctx.elicit()`, `ctx.elicit_url()`, `ctx.session.create_message()`, `ctx.session.list_roots()`, or any other `ServerSession` request helper — raises `NoBackChannelError` on such a connection instead of sending. An in-process `Client(server)` negotiates 2026-07-28 by default (see [`Client` defaults to `mode='auto'`](#client-defaults-to-modeauto)), so the first smoke test of an unchanged v1 sampling or elicitation tool fails, and setting `sampling_callback=` / `elicitation_callback=` on the client changes nothing because no request ever reaches the client.
 
-`NoBackChannelError` lives in `mcp.shared.exceptions` and subclasses `MCPError` (code `-32600`, message `Cannot send '<method>': this transport context has no back-channel for server-initiated requests.`). Raised inside an `@mcp.tool()` it reaches the client as a top-level JSON-RPC error, not `CallToolResult(is_error=True)` — see [`MCPError` raised from an `@mcp.tool()` handler now surfaces as a JSON-RPC error](#mcperror-raised-from-an-mcptool-handler-now-surfaces-as-a-json-rpc-error) — and the [Troubleshooting](troubleshooting.md) page walks through the client-side traceback. The same exception is raised on a legacy session against a `stateless_http=True` server, and on the request-scoped channel of a stateful legacy session against a `json_response=True` server (a JSON body carries exactly one response, so a mid-request `ctx.elicit()` cannot ride it; the session's standalone `GET` stream still carries unrelated messages) — both places v1 dropped the message and stalled ([`Server.run()` no longer takes a `stateless` flag](#serverrun-no-longer-takes-a-stateless-flag)). Notifications never raise it: `send_log_message()`, `send_tool_list_changed()`, and the other notification helpers are dropped with a debug log where no channel exists, and `UrlElicitationRequiredError` from a tool is unaffected (it is an error response, not a request).
+`NoBackChannelError` is exported from the top-level `mcp` package (`from mcp import NoBackChannelError`; it lives in `mcp.shared.exceptions`) and subclasses `MCPError` (code `-32600`, message `Cannot send '<method>': this transport context has no back-channel for server-initiated requests.`). Raised inside an `@mcp.tool()` it reaches the client as a top-level JSON-RPC error, not `CallToolResult(is_error=True)` — see [`MCPError` raised from an `@mcp.tool()` handler now surfaces as a JSON-RPC error](#mcperror-raised-from-an-mcptool-handler-now-surfaces-as-a-json-rpc-error) — and the [Troubleshooting](troubleshooting.md) page walks through the client-side traceback. The same exception is raised on a legacy session against a `stateless_http=True` server, and on the request-scoped channel of a stateful legacy session against a `json_response=True` server (a JSON body carries exactly one response, so a mid-request `ctx.elicit()` cannot ride it; the session's standalone `GET` stream still carries unrelated messages) — both places v1 dropped the message and stalled ([`Server.run()` no longer takes a `stateless` flag](#serverrun-no-longer-takes-a-stateless-flag)). Notifications never raise it: `send_log_message()`, `send_tool_list_changed()`, and the other notification helpers are dropped with a debug log where no channel exists, and `UrlElicitationRequiredError` from a tool is unaffected (it is an error response, not a request).
 
 Two ways to migrate:
 

docs/whats-new.md

@@ -24,6 +24,8 @@ from mcp.server import MCPServer  # v1: from mcp.server.fastmcp import FastMCP
 mcp = MCPServer("Demo")  # v1: FastMCP("Demo")
 ```
 
+Both halves of the SDK are also on the top-level package, so `from mcp import MCPServer, Client` works.
+
 It is also, for a decorator-built server, most of the port. `@mcp.tool()`, `@mcp.resource()`, and `@mcp.prompt()` accept what they accepted in v1 (`@mcp.resource()` adds one optional `security=` keyword), and the input schema still comes from your type hints. Around the edges: everything under `mcp.server.fastmcp.*` now lives under `mcp.server.mcpserver.*`, `ctx.fastmcp` is `ctx.mcp_server`, `get_context()` is gone (declare a `ctx: Context` parameter instead), and the exception base `FastMCPError` is `MCPServerError`. The **[Migration Guide](migration.md#fastmcp-renamed-to-mcpserver)** has the import table.
 
 ### `Resolve`: the new way to ask the user for input

docs_src/subscriptions/tutorial005.py

@@ -1,7 +1,7 @@
 import anyio
 
 from mcp import Client
-from mcp.client.subscriptions import SubscriptionLost
+from mcp.client import SubscriptionLost
 
 from .tutorial003 import read_board
 

pyproject.toml

@@ -203,6 +203,7 @@ select = [
     "F",      # pyflakes
     "I",      # isort
     "PERF",   # Perflint
+    "RUF022", # unsorted-dunder-all: keep `__all__` sorted
     "UP",     # pyupgrade
     "TID251", # https://docs.astral.sh/ruff/rules/banned-api/
 ]
@@ -219,6 +220,8 @@ max-complexity = 24 # Default is 10
 "__init__.py" = ["F401"]
 # The mcp.types package is an alias that mirrors mcp_types namespaces by design.
 "src/mcp/types/*.py" = ["F403"]
+# mcp_types' __all__ is grouped by section comments (capabilities, content types, requests, ...) rather than sorted.
+"src/mcp-types/mcp_types/__init__.py" = ["RUF022"]
 # Generated by scripts/gen_surface_types.py: raw datamodel-codegen output (TID251 lifts the repo-wide RootModel ban for these generated validators).
 "src/mcp-types/mcp_types/_v*/__init__.py" = ["D212", "E501", "I001", "TID251", "UP007", "UP037"]
 "tests/server/mcpserver/test_func_metadata.py" = ["E501"]

src/mcp-types/mcp_types/methods.py

@@ -27,7 +27,6 @@
     "CLIENT_NOTIFICATIONS",
     "CLIENT_REQUESTS",
     "CLIENT_RESULTS",
-    "CacheableMethod",
     "INPUT_REQUIRED_METHODS",
     "MONOLITH_NOTIFICATIONS",
     "MONOLITH_REQUESTS",
@@ -37,6 +36,7 @@
     "SERVER_RESULTS",
     "SPEC_CLIENT_METHODS",
     "SPEC_CLIENT_NOTIFICATION_METHODS",
+    "CacheableMethod",
     "is_input_required",
     "parse_client_notification",
     "parse_client_request",

src/mcp-types/mcp_types/version.py

@@ -10,14 +10,14 @@
 from typing import Final
 
 __all__ = [
-    "KNOWN_PROTOCOL_VERSIONS",
     "HANDSHAKE_PROTOCOL_VERSIONS",
-    "MODERN_PROTOCOL_VERSIONS",
-    "SUPPORTED_PROTOCOL_VERSIONS",
-    "LATEST_PROTOCOL_VERSION",
+    "KNOWN_PROTOCOL_VERSIONS",
     "LATEST_HANDSHAKE_VERSION",
     "LATEST_MODERN_VERSION",
+    "LATEST_PROTOCOL_VERSION",
+    "MODERN_PROTOCOL_VERSIONS",
     "OLDEST_SUPPORTED_VERSION",
+    "SUPPORTED_PROTOCOL_VERSIONS",
     "is_version_at_least",
 ]
 

src/mcp/__init__.py

@@ -56,7 +56,6 @@
     ToolUseContent,
     UnsubscribeRequest,
 )
-from mcp_types import Role as SamplingRole
 
 # Bind the `mcp.types` submodule on the package, as v1's `from .types import
 # ...` did, so `import mcp` followed by `mcp.types.Tool` keeps working.
@@ -66,9 +65,10 @@
 from .client.session import ClientSession
 from .client.session_group import ClientSessionGroup
 from .client.stdio import StdioServerParameters, stdio_client
+from .server.mcpserver import MCPServer
 from .server.session import ServerSession
 from .server.stdio import stdio_server
-from .shared.exceptions import MCPDeprecationWarning, MCPError, UrlElicitationRequiredError
+from .shared.exceptions import MCPDeprecationWarning, MCPError, NoBackChannelError, UrlElicitationRequiredError
 from .shared.uri_template import InvalidUriTemplate, UriTemplate
 
 __all__ = [
@@ -93,6 +93,7 @@
     "InitializeResult",
     "InitializedNotification",
     "InputRequiredRoundsExceededError",
+    "InvalidUriTemplate",
     "JSONRPCError",
     "JSONRPCRequest",
     "JSONRPCResponse",
@@ -105,22 +106,23 @@
     "LoggingMessageNotification",
     "MCPDeprecationWarning",
     "MCPError",
+    "MCPServer",
+    "NoBackChannelError",
     "Notification",
     "PingRequest",
     "ProgressNotification",
     "PromptsCapability",
     "ReadResourceRequest",
     "ReadResourceResult",
     "Resource",
-    "ResourcesCapability",
     "ResourceUpdatedNotification",
+    "ResourcesCapability",
     "RootsCapability",
     "SamplingCapability",
     "SamplingContent",
     "SamplingContextCapability",
     "SamplingMessage",
     "SamplingMessageContentBlock",
-    "SamplingRole",
     "SamplingToolsCapability",
     "ServerCapabilities",
     "ServerNotification",
@@ -134,12 +136,11 @@
     "Tool",
     "ToolChoice",
     "ToolResultContent",
-    "ToolsCapability",
     "ToolUseContent",
+    "ToolsCapability",
     "UnsubscribeRequest",
     "UriTemplate",
     "UrlElicitationRequiredError",
-    "InvalidUriTemplate",
     "stdio_client",
     "stdio_server",
 ]

src/mcp/cli/__init__.py

@@ -2,5 +2,4 @@
 
 from .cli import app
 
-if __name__ == "__main__":  # pragma: no cover
-    app()
+__all__ = ["app"]

src/mcp/client/__init__.py

@@ -21,6 +21,7 @@
     advertise,
 )
 from mcp.client.session import ClientSession, IncomingMessage
+from mcp.client.subscriptions import ListenNotSupportedError, Subscription, SubscriptionLost
 
 __all__ = [
     "CacheConfig",
@@ -32,12 +33,15 @@
     "ClientExtension",
     "ClientRequestContext",
     "ClientSession",
-    "IncomingMessage",
     "InMemoryResponseCacheStore",
+    "IncomingMessage",
     "InputRequiredRoundsExceededError",
+    "ListenNotSupportedError",
     "NotificationBinding",
     "ResponseCacheStore",
     "ResultClaim",
+    "Subscription",
+    "SubscriptionLost",
     "Transport",
     "UnexpectedClaimedResult",
     "advertise",