Split the client SDK into a standalone mcp-client package

Author: Kludex

.github/workflows/deploy-docs.yml

@@ -17,6 +17,7 @@ on:
       - mkdocs.yml
       - src/mcp/**
       - src/mcp-types/**
+      - src/mcp-client/**
       - scripts/build-docs.sh
       - scripts/docs/**
       - pyproject.toml

.github/workflows/publish-pypi.yml

@@ -29,6 +29,7 @@ jobs:
       - name: Build
         run: |
           uv build --package mcp
+          uv build --package mcp-client
           uv build --package mcp-types
 
       - name: Upload artifacts

.github/workflows/shared.yml

@@ -48,6 +48,31 @@ jobs:
           uv run --isolated --no-project --with ./src/mcp-types python -c \
             "import mcp_types, mcp_types.jsonrpc, mcp_types.methods, mcp_types.version, mcp_types._v2025_11_25, mcp_types._v2026_07_28"
 
+  packages:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        with:
+          version: 0.9.5
+      - name: Build all distributions
+        run: |
+          uv build --package mcp-types
+          uv build --package mcp-client
+          uv build --package mcp
+      - name: Exercise the client wheel and sdist without the server SDK
+        run: |
+          for package in dist/mcp_client-*.whl dist/mcp_client-*.tar.gz; do
+            uv run --isolated --no-project --find-links dist --with "$package" \
+              python scripts/check_client_package.py
+          done
+      - name: Import the full SDK with the client package first
+        run: |
+          uv run --isolated --no-project --find-links dist --with dist/mcp-*.whl python -c \
+            'import mcp_client, mcp; from typing import get_type_hints; assert mcp.Client is mcp_client.Client; get_type_hints(mcp.Client)'
+
   test:
     name: test (${{ matrix.python-version }}, ${{ matrix.dep-resolution.name }}, ${{ matrix.os }})
     runs-on: ${{ matrix.os }}

DEPENDENCY_POLICY.md

@@ -4,7 +4,7 @@
 
 ## How requirements are declared
 
-Every runtime dependency is a `>=` floor set to the oldest version that provides what the SDK uses, with no upper bound unless a dependency's next major is known to break the SDK. The one exception is `mcp-types`, the wire-types package released in lockstep with `mcp`: each `mcp` release requires exactly its own version of it, so it is the other half of the SDK rather than an independent constraint.
+Every runtime dependency is a `>=` floor set to the oldest version that provides what the SDK uses, with no upper bound unless a dependency's next major is known to break the SDK. The exceptions are `mcp-client` and `mcp-types`, which release in lockstep with `mcp`: each `mcp` release requires exactly its own version of both, and `mcp-client` requires the matching `mcp-types`. They are parts of the SDK rather than independent constraints.
 
 ## When a floor moves
 

README.md

@@ -46,6 +46,10 @@ uv add "mcp[cli]"      # or: pip install "mcp[cli]"
 
 The `cli` extra adds the `mcp` command-line tool (`mcp dev`, `mcp run`, `mcp install`) on top of the SDK; install plain `mcp` if you don't need it. For one-off commands, `uv run --with "mcp[cli]" mcp ...` works without a project.
 
+For a client-only project, use `uv add mcp-client` and `from mcp_client import Client`.
+It includes the client transports and OAuth support without the HTTP server dependencies.
+See [client-only installation](https://py.sdk.modelcontextprotocol.io/get-started/installation/#client-only-installation).
+
 ## A server in 15 lines
 
 Create a `server.py`:

RELEASE.md

@@ -7,7 +7,8 @@ move; this is the mechanics.
 
 1. Change the dependency version in `pyproject.toml`. The root `mcp` project's
    runtime dependencies are dynamic and live under
-   `[tool.hatch.metadata.hooks.uv-dynamic-versioning].dependencies`.
+   `[tool.hatch.metadata.hooks.uv-dynamic-versioning].dependencies`, as do
+   `mcp-client`'s dependencies in `src/mcp-client/pyproject.toml`.
 2. Regenerate the lock with `uv lock` (or `uv lock --upgrade-package <package>`
    to move just that package's locked version). The committed `uv.lock` is a
    normal (default-strategy) resolution; the `lowest-direct` resolution that
@@ -19,8 +20,8 @@ move; this is the mechanics.
 Two branches ship, and the package version comes from the git tag
 (`uv-dynamic-versioning`). Publishing a GitHub release runs `publish-pypi.yml`
 **from the tagged commit**, so the workflow that fires is the tagged branch's
-own: a `main` tag builds and publishes two distributions (`mcp` and
-`mcp-types`, lock-stepped via `Requires-Dist: mcp-types=={{ version }}`), and a
+own: a `main` tag builds and publishes three distributions (`mcp`,
+`mcp-client`, and `mcp-types`, with exact matching-version dependencies), and a
 `v1.x` tag builds and publishes `mcp` only.
 
 | Line                         | Branch | Tag                       | GitHub release flags                  |
@@ -29,11 +30,13 @@ own: a `main` tag builds and publishes two distributions (`mcp` and
 | Maintenance (previous major) | `v1.x` | `v1.X.Y`                  | not a pre-release; **not** Latest     |
 | Pre-releases                 | `main` | `v2.X.YaN` / `bN` / `rcN` | **Pre-release** ticked, never Latest  |
 
-The `Development Status` classifier in both `pyproject.toml` files is
+The `Development Status` classifier in all three `pyproject.toml` files is
 permanently `5 - Production/Stable`; it is not bumped as part of any release.
 The `mcp-types` PyPI project carries the same trusted publisher as `mcp` (this
-repository, workflow `publish-pypi.yml`, environment `release`). For a release
-cut from `main`, if only some of the four files upload, fix the cause and
+repository, workflow `publish-pypi.yml`, environment `release`). Before the
+first `mcp-client` release, verify ownership of the existing PyPI project and
+configure that same trusted publisher for it too. For a release cut from `main`, if only some of the six files upload,
+correct the cause and
 re-run the publish job — its `skip-existing` setting makes it skip whatever
 already landed (the `v1.x` workflow publishes a single distribution and has no
 such setting).
@@ -77,7 +80,7 @@ before the tag.
    URLs (relative links don't resolve in GitHub release bodies).
 5. If a stable release turns out to be broken, yank it on PyPI and release the
    fix as the next patch version. Never delete a release from PyPI — version
-   numbers cannot be reused. Yank `mcp` and `mcp-types` together (they are one
+   numbers cannot be reused. Yank `mcp`, `mcp-client`, and `mcp-types` together (they are one
    release), and set the yank reason and the GitHub release notes to point at
    the replacement version, since yanking doesn't stop `==` pins from installing
    the broken version.
@@ -134,6 +137,6 @@ specifier that names a pre-release version, or `--pre`.
 4. Curate the release notes: what changed since the previous pre-release, what
    is known-incomplete, the install line (`pip install mcp==2.X.YbN`), and a
    link to the migration guide, with absolute URLs.
-5. If a pre-release turns out to be broken, yank both `mcp` and `mcp-types` on PyPI
+5. If a pre-release turns out to be broken, yank `mcp`, `mcp-client`, and `mcp-types` on PyPI
    and cut the next one, pointing the yank reason and the GitHub release notes
    at the replacement version.

VERSIONING.md

@@ -4,11 +4,11 @@ What a version number of `mcp` promises: which changes can arrive in a minor rel
 
 ## The version number
 
-[Semantic Versioning](https://semver.org/) semantics in [PEP 440](https://peps.python.org/pep-0440/) syntax, taken from the git tag: in `2.X.Y`, **X** (minor) carries new functionality and every non-breaking change, **Y** (patch) carries bug fixes only, and a breaking change to the public API lands only in a new **major**. Pre-releases are cut from `main` as `aN`/`bN`/`rcN`; installers prefer final releases by default, so an unpinned `pip install mcp` stays on a stable release whenever one satisfies your requirement. `mcp` and its wire-types package `mcp-types` release in lockstep, each `mcp` requiring exactly the matching `mcp-types`.
+[Semantic Versioning](https://semver.org/) semantics in [PEP 440](https://peps.python.org/pep-0440/) syntax, taken from the git tag: in `2.X.Y`, **X** (minor) carries new functionality and every non-breaking change, **Y** (patch) carries bug fixes only, and a breaking change to the public API lands only in a new **major**. Pre-releases are cut from `main` as `aN`/`bN`/`rcN`; installers prefer final releases by default, so an unpinned `pip install mcp` stays on a stable release whenever one satisfies your requirement. `mcp`, `mcp-client`, and `mcp-types` release in lockstep. Each `mcp` requires exactly the matching `mcp-client` and `mcp-types`; `mcp-client` also requires exactly the matching `mcp-types`.
 
 ## The public API
 
-The promise covers every name exported by `mcp` and `mcp_types` (their `__all__`), the import paths, signatures, and behavior documented on the [documentation site](https://py.sdk.modelcontextprotocol.io/) and in its [API Reference](https://py.sdk.modelcontextprotocol.io/api/mcp/). It does not cover underscore-prefixed names, undocumented modules, or the wording of log lines, warnings, and exception messages (their types and documented raise conditions are covered). APIs labelled **provisional** (for example the middleware chain) may still change in a minor release; **experimental** APIs are opt-in previews.
+The promise covers every name exported by `mcp`, `mcp_client`, and `mcp_types` (their `__all__`), the import paths, signatures, and behavior documented on the [documentation site](https://py.sdk.modelcontextprotocol.io/) and in its [API Reference](https://py.sdk.modelcontextprotocol.io/api/mcp/). It does not cover underscore-prefixed names, undocumented modules, or the wording of log lines, warnings, and exception messages (their types and documented raise conditions are covered). APIs labelled **provisional** (for example the middleware chain) may still change in a minor release; **experimental** APIs are opt-in previews.
 
 ## Breaking and non-breaking changes
 

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.shared.exceptions.MCPError: {'search'} already exist in group tools.
+    mcp_client.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.shared.exceptions.MCPDeprecationWarning: The logging capability is deprecated as of 2026-07-28 (SEP-2577).
+    mcp_client.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/get-started/installation.md

@@ -21,10 +21,45 @@ These docs describe **v2**, the current stable release line:
     covers every one. If your *package* depends on `mcp` and isn't ready to migrate, keep a
     `<2` upper bound (for example `mcp>=1.28,<2`) so an unpinned resolve stays on the 1.x line.
 
+## Client-only installation
+
+```bash
+uv add mcp-client
+```
+
+```python
+import anyio
+
+from mcp_client import Client
+
+
+async def main() -> None:
+    async with Client("http://localhost:8000/mcp") as client:
+        tools = await client.list_tools()
+        for tool in tools.tools:
+            print(tool.name)
+
+
+anyio.run(main)
+```
+
+Run this example against an MCP server listening at `http://localhost:8000/mcp`.
+
+Use `mcp-client` when you only connect to servers. It includes the client transports,
+OAuth support, and shared protocol machinery without installing Starlette, Uvicorn,
+`sse-starlette`, or `python-multipart`. Import client APIs from `mcp_client`, OAuth
+support from `mcp_client.client.auth`, and protocol types from `mcp_types`.
+
+Install `mcp` if you also build servers, use the CLI, or pass a server instance to
+`Client(server)` for in-process testing. Existing `mcp` imports keep working and
+refer to the same client implementation. All three distributions release together;
+`mcp` requires its exact `mcp-client` version, which requires its exact `mcp-types` version.
+
 ## What gets installed
 
 You don't need to know any of this to use the SDK, but if you're wondering what each dependency is for:
 
+* `mcp-client`: the client API, transports, OAuth support, and shared protocol machinery, versioned in lockstep with the SDK.
 * `mcp-types`: every protocol type (requests, results, content blocks) as its own package, versioned in lockstep with the SDK. Code that depends on `mcp` imports it through the `mcp.types` alias (every `from mcp.types import ...` in these docs); import `mcp_types` directly only in a project that installs `mcp-types` without the SDK.
 * [`anyio`](https://anyio.readthedocs.io/): the async runtime. The whole SDK is written against anyio, so it runs on either `asyncio` or `trio`.
 * [`pydantic`](https://docs.pydantic.dev/): what every `mcp.types` model is built on, plus all schema generation and validation.