Preserve full-SDK compatibility after the client split

Author: Kludex

docs/client/session-groups.md

@@ -32,7 +32,7 @@ Create a `ClientSessionGroup` and call **`connect_to_server`** once per server:
     Put `client.py` next to the two servers and run it. The second `connect_to_server` refuses:
 
     ```text
-    mcp_client.shared.exceptions.MCPError: {'search'} already exist in group tools.
+    mcp.shared.exceptions.MCPError: {'search'} already exist in group tools.
     ```
 
     That is an `MCPError`, raised before anything from the second server is registered. A name must

docs/deprecated.md

@@ -123,7 +123,7 @@ That is the whole API. There is no per-method switch, and you don't want one: th
     `Error executing tool old_log`, and the captured server log names the culprit:
 
     ```text
-    mcp_client.shared.exceptions.MCPDeprecationWarning: The logging capability is deprecated as of 2026-07-28 (SEP-2577).
+    mcp.shared.exceptions.MCPDeprecationWarning: The logging capability is deprecated as of 2026-07-28 (SEP-2577).
     ```
 
     One line of pytest configuration, and a deprecated call can never sneak back into your

docs/run/legacy-clients.md

@@ -133,7 +133,7 @@ Two things about it matter more than what it does.
     The whole request fails, as a top-level protocol error:
 
     ```text
-    mcp_client.shared.exceptions.MCPError: Cannot send 'elicitation/create': this transport context has no back-channel for server-initiated requests.
+    mcp.shared.exceptions.MCPError: Cannot send 'elicitation/create': this transport context has no back-channel for server-initiated requests.
     ```
 
     `Resolve` did not save you. On a `2025-11-25` connection it *has* to send `elicitation/create`,

docs/servers/handling-errors.md

@@ -64,7 +64,7 @@ Now swap `ToolError` for `MCPError`.
     Same lookup, same miss, but now the call *raises* on the client side instead of returning:
 
     ```text
-    mcp_client.shared.exceptions.MCPError: No book titled 'Nothing' in the catalog.
+    mcp.shared.exceptions.MCPError: No book titled 'Nothing' in the catalog.
     ```
 
     The first version handed the model a sentence it could react to. This one hands it nothing.

docs/servers/prompts.md

@@ -59,7 +59,7 @@ That is the entire life of a prompt: listed by name, rendered on demand, dropped
     request itself fails with a JSON-RPC error (code `-32603`):
 
     ```text
-    mcp_client.shared.exceptions.MCPError: Internal server error
+    mcp.shared.exceptions.MCPError: Internal server error
     ```
 
     There is no tool-style error result to hand back to a model, because no model is in the loop:

docs/troubleshooting.md

@@ -39,7 +39,7 @@ async def main() -> None:
     +-+---------------- 1 ----------------
       | Traceback (most recent call last):
       |   ...
-      | mcp_client.shared.exceptions.MCPError: No forecast for 'Atlantis'.
+      | mcp.shared.exceptions.MCPError: No forecast for 'Atlantis'.
       +------------------------------------
 ```
 
@@ -167,7 +167,7 @@ async with Client("https://mcp.example.com/mcp") as client:
 ```
 
 ```text
-mcp_client.shared.exceptions.MCPError: Server returned an error response
+mcp.shared.exceptions.MCPError: Server returned an error response
 ```
 
 The words the server actually sent, `421` and `Invalid Host header`, never reach you: the 421 body has no `Content-Type: application/json`, so the client cannot parse it. They are in the **server's log**, which is where to look next:
@@ -334,7 +334,7 @@ async def test_book_table() -> None:
 ```
 
 ```text
-mcp_client.shared.exceptions.MCPError: Cannot send 'elicitation/create': this transport context has no back-channel for server-initiated requests.
+mcp.shared.exceptions.MCPError: Cannot send 'elicitation/create': this transport context has no back-channel for server-initiated requests.
 ```
 
 **A legacy connection on a `stateless_http=True` server.** Statelessness means every request is its own world: no session, no server-to-client stream, and so nowhere to send an `elicitation/create` (or `sampling/createMessage`, or `roots/list`) even for the era that has them:
@@ -375,7 +375,7 @@ async def main() -> None:
 ```
 
 ```text
-mcp_client.shared.exceptions.MCPError: Invalid or expired requestState
+mcp.shared.exceptions.MCPError: Invalid or expired requestState
 ```
 
 The message is deliberately frozen: the wire never reveals which check failed. The reason goes to the **server log**, and reading it is the whole diagnosis:

scripts/check_client_package.py

@@ -12,12 +12,21 @@
 
 import anyio
 import mcp_client
+from mcp_client.shared import exceptions
 from mcp_client.shared.memory import MessageStream, create_client_server_memory_streams
 from mcp_client.shared.message import SessionMessage
 from mcp_types import JSONRPCRequest, JSONRPCResponse, ListToolsResult, Tool
 
 get_type_hints(mcp_client.Client.__init__)
 
+for error_type in (
+    exceptions.MCPError,
+    exceptions.MCPDeprecationWarning,
+    exceptions.NoBackChannelError,
+    exceptions.UrlElicitationRequiredError,
+):
+    assert error_type.__module__ == "mcp_client.shared.exceptions"
+
 for name in ("mcp", "starlette", "uvicorn", "sse_starlette", "multipart"):
     assert importlib.util.find_spec(name) is None, name
 

src/mcp-client/mcp_client/client/client.py

@@ -8,7 +8,7 @@
 from collections.abc import Awaitable, Callable, Mapping, Sequence
 from contextlib import AbstractAsyncContextManager, AsyncExitStack
 from dataclasses import KW_ONLY, dataclass, field
-from typing import Any, Literal, TypeVar, cast
+from typing import Any, Literal, TypeAlias, TypeVar, cast
 
 import anyio
 import anyio.lowlevel
@@ -40,7 +40,7 @@
     ServerCapabilities,
 )
 from mcp_types.version import HANDSHAKE_PROTOCOL_VERSIONS, MODERN_PROTOCOL_VERSIONS
-from typing_extensions import Protocol, deprecated
+from typing_extensions import Protocol, deprecated, runtime_checkable
 
 from mcp_client.client._input_required import DEFAULT_INPUT_REQUIRED_MAX_ROUNDS, run_input_required_driver
 from mcp_client.client._probe import negotiate_auto
@@ -95,12 +95,17 @@ async def connect(exit_stack: AsyncExitStack, _mode: ConnectMode, _raise_excepti
     return connect
 
 
-class _InProcessServer(Protocol):
+@runtime_checkable
+class _ServerConnector(Protocol):
     async def __mcp_client_connect__(
         self, exit_stack: AsyncExitStack, mode: str, raise_exceptions: bool
     ) -> Dispatcher[Any]: ...
 
 
+# The full SDK rebinds this annotation alias, not the runtime-checkable protocol.
+_InProcessServer: TypeAlias = _ServerConnector
+
+
 def _connected(value: _T | None) -> _T:
     """Narrow a post-handshake session attribute from ``T | None`` to ``T``.
 
@@ -355,14 +360,14 @@ def __post_init__(self) -> None:
         self._folded_extensions = _fold_extensions(self.extensions)
 
         srv = self.server
-        if isinstance(srv, str):
+        if isinstance(srv, _ServerConnector):
+            self._connect = srv.__mcp_client_connect__
+        elif isinstance(srv, str):
             self._connect = _connect_transport(streamable_http_client(srv))
         elif isinstance(srv, StdioServerParameters):
             self._connect = _connect_transport(stdio_client(srv))
-        elif isinstance(srv, AbstractAsyncContextManager):
-            self._connect = _connect_transport(srv)
         else:
-            self._connect = cast(_InProcessServer, srv).__mcp_client_connect__
+            self._connect = _connect_transport(srv)
 
         if self.cache is not None:
             config = self.cache

src/mcp/client/__init__.py

@@ -52,11 +52,49 @@
 from mcp_client.client import (
     advertise as advertise,
 )
-from mcp_client.client import (
+
+from . import (
+    _input_required as _input_required,
+)
+from . import (
+    _memory as _memory,
+)
+from . import (
+    _probe as _probe,
+)
+from . import (
+    _transport as _transport,
+)
+from . import (
+    caching as caching,
+)
+from . import (
+    client as client,
+)
+from . import (
+    context as context,
+)
+from . import (
+    extension as extension,
+)
+from . import (
+    session as session,
+)
+from . import (
+    session_group as session_group,
+)
+from . import (
+    sse as sse,
+)
+from . import (
     stdio as stdio,
 )
-
-from . import _memory as _memory
+from . import (
+    streamable_http as streamable_http,
+)
+from . import (
+    subscriptions as subscriptions,
+)
 
 __all__ = [
     "CacheConfig",

src/mcp/client/auth/__init__.py

@@ -20,6 +20,10 @@
     TokenStorage as TokenStorage,
 )
 
+from . import exceptions as exceptions
+from . import oauth2 as oauth2
+from . import utils as utils
+
 __all__ = [
     "AuthorizationCodeResult",
     "OAuthClientProvider",