Present v2 as the stable release across the README, docs, and policies (#3178)

maxisbey · web-flow · commit 6f69a3758ebf · 2026-07-28T14:31:36.000+01:00
diff --git a/.github/ISSUE_TEMPLATE/v2-feedback.yaml b/.github/ISSUE_TEMPLATE/v2-feedback.yaml
@@ -1,15 +1,15 @@
 name: v2 feedback
 description: Bugs, API friction, or docs gaps in v2 of the SDK
 title: "[v2] "
-labels: ["v2-alpha"]
+labels: ["v2"]
 
 body:
   - type: markdown
     attributes:
       value: |
-        Thanks for trying v2. Anything that broke, surprised you, or slowed you down is useful — API feedback is explicitly welcome while v2 is in pre-release.
+        Anything in v2 that broke, surprised you, or slowed you down is useful, including API friction and docs gaps.
 
-        Docs: https://py.sdk.modelcontextprotocol.io/v2/ · Migration from v1: https://py.sdk.modelcontextprotocol.io/v2/migration/
+        Docs: https://py.sdk.modelcontextprotocol.io/ · Migration from v1: https://py.sdk.modelcontextprotocol.io/migration/
 
   - type: textarea
     id: what
diff --git a/AGENTS.md b/AGENTS.md
@@ -2,16 +2,16 @@
 
 ## Branching Model
 
-<!-- TODO: drop this section once v2 ships and main becomes the stable line -->
-
-- `main` is currently the V2 rework.
-- Breaking changes are expected here — removing or replacing an API must be
-  intentional. Adding a replacement API or `@deprecated` shim must likewise be
-  a deliberate design choice, not bolted on for free.
-- Breaking changes (including those softened by a backwards-compatibility
-  shim) must be documented in `docs/migration.md`.
-- `v1.x` is the release branch for the current stable line. Backport PRs target
-  this branch and use a `[v1.x]` title prefix.
+- `main` is the current stable line (v2); releases are cut from it (see
+  `RELEASE.md`).
+- Removing or replacing an API must be intentional, and what shipped in 2.x
+  is public surface. Adding a replacement API or `@deprecated` shim is
+  likewise a deliberate design choice, not bolted on for free.
+- Changes that break code written against v1 (including those softened by a
+  backwards-compatibility shim) must be documented in `docs/migration.md`.
+- `v1.x` is the maintenance branch for the previous major. Backport PRs
+  target it and use a `[v1.x]` title prefix; only critical bug fixes and
+  security fixes land there.
 - `README.md` documents v2. The v1 README lives on the `v1.x` branch.
 
 ## Package Management
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -76,11 +76,11 @@ uv tool install pre-commit --with pre-commit-uv --force-reinstall
 
    | Change Type | Target Branch | Example |
    |-------------|---------------|---------|
-   | New features, breaking changes | `main` | New APIs, refactors |
+   | New features and fixes for v2 | `main` | New APIs, refactors |
    | Security fixes for v1 | `v1.x` | Critical patches |
-   | Bug fixes for v1 | `v1.x` | Non-breaking fixes |
+   | Critical bug fixes for v1 | `v1.x` | Backports of severe bugs |
 
-   > **Note:** `main` is the v2 development branch. Breaking changes are welcome on `main`. The `v1.x` branch receives only security and critical bug fixes.
+   > **Note:** `main` is the current stable line (v2). The `v1.x` branch is the previous major's maintenance line and receives only security and critical bug fixes.
 
 2. Create a new branch from your chosen base branch
 
diff --git a/README.md b/README.md
@@ -13,18 +13,18 @@
 
 </div>
 
-> [!CAUTION]
-> **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.
+> [!NOTE]
+> **This is v2 of the MCP Python SDK, the current stable release line.** It is a major rework of the SDK, both to support the [2026-07-28 MCP specification](https://blog.modelcontextprotocol.io/posts/2026-07-28-release-candidate/) (and every earlier revision) and to fix long-standing architectural issues. Coming from v1? See [What's new in v2](https://py.sdk.modelcontextprotocol.io/whats-new/) for the tour of what changed and the [migration guide](https://py.sdk.modelcontextprotocol.io/migration/) for every breaking change.
 >
-> **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.**
+> **Not ready to migrate?** v1.x lives on the [`v1.x` branch](https://github.com/modelcontextprotocol/python-sdk/tree/v1.x), continues to receive critical bug fixes and security patches, and is documented at <https://py.sdk.modelcontextprotocol.io/v1/>. Since `pip install mcp` now installs 2.x, keep a `<2` upper bound on your requirement (for example `mcp>=1.28,<2`) until you've migrated.
 >
-> v2 is a major rework of the SDK, both to support the [2026-07-28 MCP specification release](https://blog.modelcontextprotocol.io/posts/2026-07-28-release-candidate/) and to fix long-standing architectural issues. See [What's new in v2](https://py.sdk.modelcontextprotocol.io/v2/whats-new/) for the tour of what changed, and the [migration guide](https://py.sdk.modelcontextprotocol.io/v2/migration/) for every breaking change. Stable v2 is targeted for 2026-07-28, alongside the spec release. Try the pre-releases and [tell us what breaks](https://github.com/modelcontextprotocol/python-sdk/issues/new?template=v2-feedback.yaml), or discuss in [#python-sdk-dev on the MCP Contributors Discord](https://discord.gg/6CSzBmMkjX).
+> Something rough, confusing, or broken? [Open an issue](https://github.com/modelcontextprotocol/python-sdk/issues/new?template=v2-feedback.yaml) or find us in [#python-sdk-dev on the MCP Contributors Discord](https://discord.gg/6CSzBmMkjX).
 
 ## Documentation
 
-**The documentation lives at <https://py.sdk.modelcontextprotocol.io/v2/>.**
+**The documentation lives at <https://py.sdk.modelcontextprotocol.io/>.**
 
-It has a [Get started guide](https://py.sdk.modelcontextprotocol.io/v2/get-started/), [What's new in v2](https://py.sdk.modelcontextprotocol.io/v2/whats-new/), the [API reference](https://py.sdk.modelcontextprotocol.io/v2/api/mcp/), and the [migration guide](https://py.sdk.modelcontextprotocol.io/v2/migration/).
+It has a [Get started guide](https://py.sdk.modelcontextprotocol.io/get-started/), [What's new in v2](https://py.sdk.modelcontextprotocol.io/whats-new/), the [API reference](https://py.sdk.modelcontextprotocol.io/api/mcp/), and the [migration guide](https://py.sdk.modelcontextprotocol.io/migration/).
 
 ## What is MCP?
 
@@ -41,10 +41,10 @@ Python 3.10+.
 ## Installation
 
 ```bash
-uv add "mcp[cli]==2.0.0rc1"          # or: pip install "mcp[cli]==2.0.0rc1"
+uv add "mcp[cli]"      # or: pip install "mcp[cli]"
 ```
 
-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.
+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.
 
 ## A server in 15 lines
 
@@ -82,7 +82,7 @@ Call `add` with `a=1`, `b=2` and you get `3` back.
 
 Notice what you did **not** write: no JSON Schema (`a: int, b: int` _is_ the schema), no request parsing, no validation code, no protocol handling. Two type-hinted Python functions and a docstring.
 
-[Get started](https://py.sdk.modelcontextprotocol.io/v2/get-started/) takes it from here.
+[Get started](https://py.sdk.modelcontextprotocol.io/get-started/) takes it from here.
 
 ## A client in 10 lines
 
@@ -122,7 +122,7 @@ This project is licensed under the MIT License. See the [LICENSE](https://github
 [python-badge]: https://img.shields.io/pypi/pyversions/mcp.svg
 [python-url]: https://www.python.org/downloads/
 [docs-badge]: https://img.shields.io/badge/docs-python--sdk-blue.svg
-[docs-url]: https://py.sdk.modelcontextprotocol.io/v2/
+[docs-url]: https://py.sdk.modelcontextprotocol.io/
 [protocol-badge]: https://img.shields.io/badge/protocol-modelcontextprotocol.io-blue.svg
 [protocol-url]: https://modelcontextprotocol.io
 [spec-badge]: https://img.shields.io/badge/spec-spec.modelcontextprotocol.io-blue.svg
diff --git a/SECURITY.md b/SECURITY.md
@@ -4,12 +4,17 @@ Thank you for helping keep the Model Context Protocol and its ecosystem secure.
 
 ## Supported Versions
 
-Security fixes are released for the most recent stable (v1.x) release line.
-
-v2 pre-releases (`2.0.0aN`, …) are development snapshots: fixes land only in
-the newest pre-release, and already-published pre-releases are not patched. If
-you are testing the v2 line, track the latest pre-release; for production use,
-stay on the latest stable release.
+| Version                              | Line                    | Support                                  |
+| ------------------------------------ | ----------------------- | ---------------------------------------- |
+| 2.x (newest release)                 | current stable (`main`) | bug fixes, security fixes, new features  |
+| 1.28.x (`v1.x` branch)               | maintenance             | critical bug fixes and security fixes    |
+| < 1.28, and all pre-release versions | unsupported             | upgrade to the newest 1.28.x or to 2.x   |
+
+Only the newest release of a supported line receives fixes, so reproduce against
+it before reporting. If your project depends on `mcp` and is not yet ready for
+2.x, constrain to `mcp>=1.28,<2` and follow the
+[migration guide](https://py.sdk.modelcontextprotocol.io/migration/) when you
+migrate.
 
 ## Reporting Security Issues
 
diff --git a/docs/get-started/installation.md b/docs/get-started/installation.md
@@ -2,30 +2,24 @@
 
 The Python SDK is on PyPI as [`mcp`](https://pypi.org/project/mcp/). It requires **Python 3.10+**.
 
-These docs describe **v2**, currently a release candidate, so the version pin is not optional yet:
+These docs describe **v2**, the current stable release line:
 
 === "uv"
 
     ```bash
-    uv add "mcp[cli]==2.0.0rc1"
+    uv add "mcp[cli]"
     ```
 
 === "pip"
 
     ```bash
-    pip install "mcp[cli]==2.0.0rc1"
+    pip install "mcp[cli]"
     ```
 
-!!! 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 pre-release before you copy
-    the line above.
-
-    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.
+!!! note "Coming from v1?"
+    v2 is a major version with breaking changes; the **[Migration Guide](../migration.md)**
+    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.
 
 ## What gets installed
 
diff --git a/docs/get-started/real-host.md b/docs/get-started/real-host.md
@@ -23,17 +23,12 @@ 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.0rc1" mcp run /absolute/path/to/server.py
+uv run --with "mcp[cli]" 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.
+One command for all of them because `uv run --with` resolves the SDK into a fresh environment on the spot: it works from any directory and needs no project and no virtual environment to activate. 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.
 
-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 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)**.
+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, apart from the exact version pin the tool adds.
 
 !!! tip "If a host can't find `uv`"
     A host spawns your server with a minimal `PATH`, and `uv` may not be on it. Replace the bare
@@ -74,7 +69,7 @@ There is nothing to be mystified by. This is the entry it writes:
         "run",
         "--frozen",
         "--with",
-        "mcp[cli]==2.0.0rc1",
+        "mcp[cli]==2.0.0",
         "mcp",
         "run",
         "/absolute/path/to/server.py"
@@ -84,12 +79,12 @@ There is nothing to be mystified by. This is the entry it writes:
 }
 ```
 
-That's the launch command from the section above with two additions: the absolute path to `uv`, and `--frozen` so `uv` never rewrites a lockfile it happens to be near. It lands in `claude_desktop_config.json`, which lives at:
+That's the launch command from the section above with three additions: the absolute path to `uv`, `--frozen` so `uv` never rewrites a lockfile it happens to be near, and an exact pin to the `mcp` version you have installed. It lands in `claude_desktop_config.json`, which lives at:
 
 * **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
 * **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
 
-You can write that file by hand. `mcp install` exists so you don't make the two classic mistakes (a relative path, a missing version pin) while doing it.
+You can write that file by hand. `mcp install` exists so you don't make the classic mistake (a relative path) while doing it.
 
 Fully quit Claude Desktop (not just its window) and reopen it.
 
@@ -107,7 +102,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.0rc1" mcp run /absolute/path/to/server.py
+claude mcp add bookshop -- uv run --with "mcp[cli]" 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 +116,7 @@ Create `.cursor/mcp.json` in your project root.
   "mcpServers": {
     "bookshop": {
       "command": "uv",
-      "args": ["run", "--with", "mcp[cli]==2.0.0rc1", "mcp", "run", "/absolute/path/to/server.py"]
+      "args": ["run", "--with", "mcp[cli]", "mcp", "run", "/absolute/path/to/server.py"]
     }
   }
 }
@@ -139,7 +134,7 @@ Create `.vscode/mcp.json` in your project root.
     "bookshop": {
       "type": "stdio",
       "command": "uv",
-      "args": ["run", "--with", "mcp[cli]==2.0.0rc1", "mcp", "run", "/absolute/path/to/server.py"]
+      "args": ["run", "--with", "mcp[cli]", "mcp", "run", "/absolute/path/to/server.py"]
     }
   }
 }
@@ -156,7 +151,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.0rc1" mcp run /absolute/path/to/server.py
+uv run --with "mcp[cli]" 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,8 +169,8 @@ 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.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.
+* That command is `uv run --with "mcp[cli]" mcp run /absolute/path/to/server.py`: no venv to activate, works from any directory.
+* **Claude Desktop** is the one host `mcp install` configures for you. It writes that same command (plus the absolute path to `uv`, `--frozen`, and an exact pin to the version you have installed) into `claude_desktop_config.json`, so you never have to.
 * **Claude Code** is `claude mcp add bookshop -- <launch command>`. **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
diff --git a/docs/migration.md b/docs/migration.md
diff --git a/docs/whats-new.md b/docs/whats-new.md
