Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
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
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, 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.
> **This README documents v2 of the MCP Python SDK, currently a release candidate (`2.0.0rc2`); 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.0rc1" # or: pip install "mcp[cli]==2.0.0rc1"
uv add "mcp[cli]==2.0.0rc2" # or: pip install "mcp[cli]==2.0.0rc2"
```

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 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.0rc2"` for one-off commands.

## A server in 15 lines

Expand Down
6 changes: 3 additions & 3 deletions docs/get-started/installation.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,13 +7,13 @@ These docs describe **v2**, currently a release candidate, so the version pin is
=== "uv"

```bash
uv add "mcp[cli]==2.0.0rc1"
uv add "mcp[cli]==2.0.0rc2"
```

=== "pip"

```bash
pip install "mcp[cli]==2.0.0rc1"
pip install "mcp[cli]==2.0.0rc2"
```

!!! warning "Why the pin"
Expand All @@ -22,7 +22,7 @@ These docs describe **v2**, currently a release candidate, so the version pin is
[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 ...`.
The same applies to one-off commands: `uv run --with "mcp==2.0.0rc2" ...`, 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
14 changes: 7 additions & 7 deletions docs/get-started/real-host.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.0rc1" mcp run /absolute/path/to/server.py
uv run --with "mcp[cli]==2.0.0rc2" 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.
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.0rc1",
"mcp[cli]==2.0.0rc2",
"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.0rc1" mcp run /absolute/path/to/server.py
claude mcp add bookshop -- uv run --with "mcp[cli]==2.0.0rc2" 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.0rc1", "mcp", "run", "/absolute/path/to/server.py"]
"args": ["run", "--with", "mcp[cli]==2.0.0rc2", "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.0rc1", "mcp", "run", "/absolute/path/to/server.py"]
"args": ["run", "--with", "mcp[cli]==2.0.0rc2", "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.0rc1" mcp run /absolute/path/to/server.py
uv run --with "mcp[cli]==2.0.0rc2" 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.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.
* That command is `uv run --with "mcp[cli]==2.0.0rc2" 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
4 changes: 2 additions & 2 deletions docs/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,13 +22,13 @@ Python 3.10+.
=== "uv"

```bash
uv add "mcp[cli]==2.0.0rc1"
uv add "mcp[cli]==2.0.0rc2"
```

=== "pip"

```bash
pip install "mcp[cli]==2.0.0rc1"
pip install "mcp[cli]==2.0.0rc2"
```

The `[cli]` extra gives you the `mcp` command; you'll want it for development.
Expand Down
Loading