Skip to content

Point pre-release install pins at 2.0.0rc1 #3186

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
maxisbey merged 1 commit into from
Jul 27, 2026
Merged

Point pre-release install pins at 2.0.0rc1 #3186

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@
</div>

> [!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.**
>
Expand All @@ -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

Expand Down
10 changes: 5 additions & 5 deletions docs/get-started/installation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
16 changes: 8 additions & 8 deletions docs/get-started/real-host.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,15 +23,15 @@ 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

@cubic-dev-ai cubic-dev-ai Bot Jul 27, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2: Running these commands from a directory containing a project can let uv update its lockfile. Show --frozen in every documented launch command, matching the repository’s uv policy and the generated Claude Desktop entry.

Prompt for AI agents 
Check if this issue is valid — if so, understand the root cause and fix it. At docs/get-started/real-host.md, line 26:

<comment>Running these commands from a directory containing a project can let `uv` update its lockfile. Show `--frozen` in every documented launch command, matching the repository’s `uv` policy and the generated Claude Desktop entry.</comment>

<file context>
@@ -23,15 +23,15 @@ That is the last line of Python on this page. From here down it is all host conf
 
 ```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

</file context>


</details>

```

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.

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)**.

Expand Down Expand Up @@ -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"
Expand Down Expand Up @@ -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.
Expand All @@ -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"]
}
}
}
Expand All @@ -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"]
}
}
}
Expand All @@ -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.
Expand All @@ -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 -- <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.
Expand Down
8 changes: 4 additions & 4 deletions docs/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
6 changes: 3 additions & 3 deletions docs/whats-new.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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)**.
Expand Down
Loading