diff --git a/README.md b/README.md index 7224bb65d..4726de1dd 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,7 @@ > [!CAUTION] -> **This README documents v2 of the MCP Python SDK — a pre-release (alpha/beta) line under active development. Do not use v2 in production.** Pre-releases are published to PyPI as `2.0.0aN` / `2.0.0bN`, and **each pre-release may contain breaking changes from the previous one**. Pin an exact version and expect to update your code when you bump the pin. +> **This README documents v2 of the MCP Python SDK, currently a release candidate (`2.0.0rc1`); the stable v2 release is planned for 2026-07-28.** Do not use v2 in production yet. Pre-releases are published to PyPI as `2.0.0aN` / `2.0.0bN` / `2.0.0rcN`, and **a pre-release may still contain breaking changes from the previous one**. Pin an exact version and expect to update your code when you bump the pin. > > **v1.x is the only stable release line and remains recommended for production.** It lives on the [`v1.x` branch](https://github.com/modelcontextprotocol/python-sdk/tree/v1.x) and continues to receive critical bug fixes and security patches; see [the v1.x README](https://github.com/modelcontextprotocol/python-sdk/blob/v1.x/README.md) for its documentation. `pip` and `uv` don't select a pre-release unless you explicitly request one, so existing installs are unaffected. **If your package depends on `mcp`, add a `<2` upper bound to your version constraint (for example `mcp>=1.27,<2`) before the stable release lands.** > @@ -41,10 +41,10 @@ Python 3.10+. ## Installation ```bash -uv add "mcp[cli]==2.0.0b1" # or: pip install "mcp[cli]==2.0.0b1" +uv add "mcp[cli]==2.0.0rc1" # or: pip install "mcp[cli]==2.0.0rc1" ``` -The pin matters while v2 is in pre-release: an unpinned install resolves to the latest stable v1.x, which this README does not describe. Check [PyPI](https://pypi.org/project/mcp/#history) for the newest pre-release, and use `uv run --with "mcp==2.0.0b1"` for one-off commands. +The pin matters while v2 is in pre-release: an unpinned install resolves to the latest stable v1.x, which this README does not describe. Check [PyPI](https://pypi.org/project/mcp/#history) for the newest pre-release, and use `uv run --with "mcp==2.0.0rc1"` for one-off commands. ## A server in 15 lines diff --git a/docs/get-started/installation.md b/docs/get-started/installation.md index d39c12e39..a0c6100f1 100644 --- a/docs/get-started/installation.md +++ b/docs/get-started/installation.md @@ -2,27 +2,27 @@ The Python SDK is on PyPI as [`mcp`](https://pypi.org/project/mcp/). It requires **Python 3.10+**. -These docs describe **v2**, which is in beta, so the version pin is not optional yet: +These docs describe **v2**, currently a release candidate, so the version pin is not optional yet: === "uv" ```bash - uv add "mcp[cli]==2.0.0b1" + uv add "mcp[cli]==2.0.0rc1" ``` === "pip" ```bash - pip install "mcp[cli]==2.0.0b1" + pip install "mcp[cli]==2.0.0rc1" ``` !!! warning "Why the pin" Installers never select a pre-release unless you name one, so an unpinned `uv add "mcp[cli]"` gives you the latest **v1.x** release, which these docs do not describe. Check the - [release history](https://pypi.org/project/mcp/#history) for the newest beta before you copy + [release history](https://pypi.org/project/mcp/#history) for the newest pre-release before you copy the line above. - The same applies to one-off commands: `uv run --with "mcp==2.0.0b1" ...`, not `uv run --with mcp ...`. + The same applies to one-off commands: `uv run --with "mcp==2.0.0rc1" ...`, not `uv run --with mcp ...`. If your *package* depends on `mcp`, add a `<2` upper bound (for example `mcp>=1.27,<2`) before the stable v2 lands so the major version bump doesn't surprise you. diff --git a/docs/get-started/real-host.md b/docs/get-started/real-host.md index 4292d9b2e..ee056257c 100644 --- a/docs/get-started/real-host.md +++ b/docs/get-started/real-host.md @@ -23,7 +23,7 @@ That is the last line of Python on this page. From here down it is all host conf Every host below gets the same command: ```bash -uv run --with "mcp[cli]==2.0.0b1" mcp run /absolute/path/to/server.py +uv run --with "mcp[cli]==2.0.0rc1" mcp run /absolute/path/to/server.py ``` One command for all of them because `uv run --with` resolves the pinned SDK into a fresh environment on the spot: it works from any directory, needs no project and no virtual environment to activate, and always gets the exact `mcp` version these docs describe. That matters here more than anywhere else, because a host launches your server from *its* working directory with a near-empty environment, not from your shell. @@ -31,7 +31,7 @@ One command for all of them because `uv run --with` resolves the pinned SDK into It is also the command `mcp install` writes into Claude Desktop's config for you (below), so what you type by hand and what the tool generates agree. !!! warning "The version pin is not optional" - v2 of this SDK is in beta, and installers never select a pre-release unless you name one. An + v2 of this SDK is a release candidate, and installers never select a pre-release unless you name one. An unpinned `--with "mcp[cli]"` gives you the latest **v1.x**, which these docs do not describe. Use the exact pin from **[Installation](installation.md)**. @@ -74,7 +74,7 @@ There is nothing to be mystified by. This is the entry it writes: "run", "--frozen", "--with", - "mcp[cli]==2.0.0b1", + "mcp[cli]==2.0.0rc1", "mcp", "run", "/absolute/path/to/server.py" @@ -107,7 +107,7 @@ Fully quit Claude Desktop (not just its window) and reopen it. There is no file to edit. Register the server with the `claude` CLI; everything after `--` is the launch command. ```bash -claude mcp add bookshop -- uv run --with "mcp[cli]==2.0.0b1" mcp run /absolute/path/to/server.py +claude mcp add bookshop -- uv run --with "mcp[cli]==2.0.0rc1" mcp run /absolute/path/to/server.py ``` Run `/mcp` inside a Claude Code session to confirm `bookshop` is connected and its tools are listed. @@ -121,7 +121,7 @@ Create `.cursor/mcp.json` in your project root. "mcpServers": { "bookshop": { "command": "uv", - "args": ["run", "--with", "mcp[cli]==2.0.0b1", "mcp", "run", "/absolute/path/to/server.py"] + "args": ["run", "--with", "mcp[cli]==2.0.0rc1", "mcp", "run", "/absolute/path/to/server.py"] } } } @@ -139,7 +139,7 @@ Create `.vscode/mcp.json` in your project root. "bookshop": { "type": "stdio", "command": "uv", - "args": ["run", "--with", "mcp[cli]==2.0.0b1", "mcp", "run", "/absolute/path/to/server.py"] + "args": ["run", "--with", "mcp[cli]==2.0.0rc1", "mcp", "run", "/absolute/path/to/server.py"] } } } @@ -156,7 +156,7 @@ Two differences from Cursor's file, and they are the only two: the wrapper key i Before you touch any host config, run the launch command yourself: ```bash -uv run --with "mcp[cli]==2.0.0b1" mcp run /absolute/path/to/server.py +uv run --with "mcp[cli]==2.0.0rc1" mcp run /absolute/path/to/server.py ``` Nothing prints, and it doesn't return. That silence is correct: a stdio server is waiting for a host to speak first on stdin (`Ctrl-C` to stop it). A traceback or an immediate exit is the real bug, and now you can read it instead of guessing at it through a host. @@ -174,7 +174,7 @@ For anything past those three, **[Troubleshooting](../troubleshooting.md)** is t ## Recap * A **host** (Claude Desktop, an IDE) runs an MCP client that launches your server as a child process over stdio. Connecting means giving it one launch command. -* That command is `uv run --with "mcp[cli]==2.0.0b1" mcp run /absolute/path/to/server.py`: version-pinned, no venv to activate, works from any directory. The pin is mandatory while v2 is in beta. +* That command is `uv run --with "mcp[cli]==2.0.0rc1" mcp run /absolute/path/to/server.py`: version-pinned, no venv to activate, works from any directory. The pin is mandatory while v2 is pre-release. * **Claude Desktop** is the one host `mcp install` configures for you. It writes that same command (plus the absolute path to `uv`) into `claude_desktop_config.json`, so you never have to. * **Claude Code** is `claude mcp add bookshop -- `. **Cursor** is `.cursor/mcp.json` under `mcpServers`. **VS Code** is `.vscode/mcp.json` under `servers`, each entry with a `type`. * Absolute paths everywhere, restart the host after editing its config, and never let anything but the SDK write to stdout. diff --git a/docs/index.md b/docs/index.md index 8aa1a5b67..4c2584f90 100644 --- a/docs/index.md +++ b/docs/index.md @@ -22,21 +22,21 @@ Python 3.10+. === "uv" ```bash - uv add "mcp[cli]==2.0.0b1" + uv add "mcp[cli]==2.0.0rc1" ``` === "pip" ```bash - pip install "mcp[cli]==2.0.0b1" + pip install "mcp[cli]==2.0.0rc1" ``` The `[cli]` extra gives you the `mcp` command; you'll want it for development. -!!! warning "Pin the version while v2 is in beta" +!!! warning "Pin the version while v2 is pre-release" Installers never select a pre-release unless you name one, so an unpinned `uv add "mcp[cli]"` gives you the latest **v1.x** release, which this documentation does not describe. Check - [PyPI](https://pypi.org/project/mcp/#history) for the newest beta before you copy the line + [PyPI](https://pypi.org/project/mcp/#history) for the newest pre-release before you copy the line above. See [Installation](get-started/installation.md) for the details. ## Example diff --git a/docs/whats-new.md b/docs/whats-new.md index 4ae0de2bc..9826fa590 100644 --- a/docs/whats-new.md +++ b/docs/whats-new.md @@ -4,13 +4,13 @@ Two things happened at once in v2. The **SDK was rebuilt**: a new engine under b This page is the tour of both halves, one section per headline, each ending in the page that owns the topic. It is not the porting manual. That is the **[Migration Guide](migration.md)**: every breaking change, with before and after code. -!!! note "v2 is a beta" +!!! note "v2 is a release candidate" `pip install mcp` still installs v1.x: you opt into v2 with an exact version pin, and the API can still move before the stable release, which lands alongside the spec release. **[Installation](get-started/installation.md)** has the copy-paste install line and the pinning rules. And if anything in v2 breaks, surprises, or slows you down, [tell us](https://github.com/modelcontextprotocol/python-sdk/issues/new?template=v2-feedback.yaml): - while v2 is in beta, that is the most useful thing you can send us. + before the stable release, that is the most useful thing you can send us. ## The SDK: v1 to v2 @@ -197,7 +197,7 @@ At 2026-07-28 the standalone HTTP GET stream and `resources/subscribe` are repla ### The rest, quickly -* **Identity is optional, per-message metadata.** The request-side `clientInfo` `_meta` key is optional (the required pair is `protocolVersion` + `clientCapabilities`), and `serverInfo` moved out of the `server/discover` result body: servers stamp it into every 2026-era result's `_meta` instead (since `2.0.0b3`; [spec #3002](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/3002)). The SDK always stamps; `client.server_info` is `None` when a server does not identify itself (for example, a middleware stripped the key). **[The low-level Server](advanced/low-level-server.md)** shows the stamp on the wire. +* **Identity is optional, per-message metadata.** The request-side `clientInfo` `_meta` key is optional (the required pair is `protocolVersion` + `clientCapabilities`), and `serverInfo` moved out of the `server/discover` result body: servers stamp it into every 2026-era result's `_meta` instead (since `2.0.0rc1`; [spec #3002](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/3002)). The SDK always stamps; `client.server_info` is `None` when a server does not identify itself (for example, a middleware stripped the key). **[The low-level Server](advanced/low-level-server.md)** shows the stamp on the wire. * **Requests are routable without parsing bodies.** Modern HTTP requests carry `Mcp-Method` (and, for the three tool-ish calls, `Mcp-Name`); a tool input-schema property annotated with `x-mcp-header` is mirrored into an `Mcp-Param-*` header and cross-checked by the server ([SEP-2243](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2243)). Gateways and rate limiters can route on headers alone; the **[Migration Guide](migration.md#servers-validate-mcp-param-headers-against-the-request-body-sep-2243)** has the rules. * **Results carry cache hints.** List and read results declare `ttlMs` and `cacheScope` ([SEP-2549](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2549)); you set them per method with `cache_hints=`, and `Client` honors them with a built-in response cache. A server that sends no hints (every pre-2026 server) sees identical, uncached traffic. **[Caching hints](client/caching.md)**. * **Extensions are first class.** Servers and clients declare optional capability bundles under reverse-DNS identifiers ([SEP-2133](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2133)); the built-in `Apps` extension (MCP Apps) is the reference. **[Extensions](advanced/extensions.md)** and **[MCP Apps](advanced/apps.md)**.