Skip to content

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

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

Open
maxisbey wants to merge 1 commit into
base: main
Choose a base branch
from
+73 −87
Open

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

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 .github/ISSUE_TEMPLATE/v2-feedback.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
Expand Down
20 changes: 10 additions & 10 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
6 changes: 3 additions & 3 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
20 changes: 10 additions & 10 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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).

Check warning on line 21 in README.md

View check run for this annotation

Claude / Claude Code Review

README [!NOTE] alert renders as literal text on the immutable 2.0.0 PyPI page 

The rewritten admonition uses GitHub alert syntax (`> [!NOTE]`), which PyPI's renderer (readme_renderer, which does not enable the alerts extension) doesn't support — the 2.0.0 PyPI long description will open with the literal text "[!NOTE]" as the first visible line of the blockquote. Since this PR merges last precisely because README.md at the tag becomes the immutable PyPI long description, this is the last cheap moment to fix it: drop the `[!NOTE]` marker line (a plain blockquote renders fine
Comment on lines +16 to +21

@claude claude Bot Jul 27, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

🟡 The rewritten admonition uses GitHub alert syntax (> [!NOTE]), which PyPI's renderer (readme_renderer, which does not enable the alerts extension) doesn't support — the 2.0.0 PyPI long description will open with the literal text "[!NOTE]" as the first visible line of the blockquote. Since this PR merges last precisely because README.md at the tag becomes the immutable PyPI long description, this is the last cheap moment to fix it: drop the [!NOTE] marker line (a plain blockquote renders fine on both GitHub and PyPI) or switch to a construct PyPI renders.

Extended reasoning...

What the bug is. The rewritten top admonition (README.md lines 16–21) is a GitHub alert: a blockquote whose first line is > [!NOTE]. Alert syntax ([!NOTE], [!CAUTION], …) is a GitHub-app-layer extension, not part of the GFM spec, and PyPI's renderer does not implement it. Because pyproject.toml sets readme = "README.md" (content type text/markdown), PyPI renders the long description via readme_renderer — and that pipeline passes the marker through as literal text.

Verified empirically, not from documentation. Rendering this PR's README with the workspace's readme_renderer 45.0 wheel via readme_renderer.markdown.render(text, variant='GFM') — the exact code path warehouse uses — produces output that begins:

<blockquote><p>[!NOTE]
<strong>This is v2 of the MCP Python SDK, the current stable release line.</strong> ...

The root cause is a renderer-config fact: readme_renderer 45.0 configures its comrak backend with autolink/footnotes/header_ids/strikethrough/table/tagfilter/tasklist, but never enables comrak's alerts extension (which exists — so this is definitively a disabled feature, not an unsupported one that might quietly work). The marker line therefore survives as visible junk text at the top of the rendered page.

Why this is in scope for this PR, not merely pre-existing. The old README used > [!CAUTION] through the same mechanism, so pre-release PyPI pages (2.0.0rc1 etc.) already show a literal marker — but those pages are throwaway. This PR rewrites these exact lines, and its entire stated reason for merging last, right before the v2.0.0 tag, is that "README.md at the tagged commit is the PyPI long description." That makes this PR the artifact whose output becomes the permanent front page of the stable 2.0.0 release — and the last cheap moment to fix it, by the PR's own tagged-artifact reasoning (the same reasoning already applied to the /v2/ sidebar-URL finding).

Why existing checks don't catch it. The pre-commit README check only syncs docs_src/ snippets; the strict mkdocs build doesn't render README.md at all (it isn't a docs page); and twine check-style validation only requires the markdown to render without error — literal [!NOTE] text renders fine, it just looks wrong.

Step-by-step proof of the trigger.

  1. This PR merges; v2.0.0 is tagged at that commit.
  2. The release builds the wheel/sdist with this README as the text/markdown long description.
  3. PyPI renders it with readme_renderer's GFM variant; the alerts extension is not enabled, so the [!NOTE] line survives as text inside a plain <blockquote>.
  4. The stable release's PyPI page opens — directly under the badges — with the stray token "[!NOTE]" above the bold "This is v2 of the MCP Python SDK…" opener. PyPI metadata for a released version is immutable, so 2.0.0's page can never be fixed after the tag.

How to fix. One line, pre-tag: delete the > [!NOTE] marker line so the block is a plain blockquote — it renders acceptably on both GitHub and PyPI, losing only GitHub's colored NOTE styling. (Alternatively, keep the alert on GitHub and strip it at build time, but that machinery isn't worth it for one admonition.)

Severity. Nit: purely cosmetic, nothing breaks, twine check and the docs build both pass — but the blemish is permanent on the release's highest-visibility artifact, and only this PR can still fix it cheaply.


## 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/).
Comment on lines +25 to +27

@claude claude Bot Jul 26, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

🟡 The /v2/ → root URL sweep missed three non-Markdown files: pyproject.toml:145 and src/mcp-types/pyproject.toml:34 still set Documentation = "https://py.sdk.modelcontextprotocol.io/v2/", and mkdocs.yml:7 still has site_url: .../v2/. The two pyproject URLs ship in the immutable 2.0.0 wheel metadata (the PyPI sidebar Documentation link) via the exact same tagged-artifact mechanism this PR cites for updating README.md, so the 2.0.0 PyPI page would show a /v2/ sidebar link next to a README that uses root URLs — worth fixing before the tag.

Extended reasoning...

What was missed. This PR's stated purpose is that root doc links become the canonical v2 docs at the stable release, and it flips every https://py.sdk.modelcontextprotocol.io/v2/... URL to the site root across README.md, the docs pages, and the v2-feedback issue template. Three occurrences in non-Markdown files were left behind (verified at this PR's HEAD):

  • pyproject.toml:145 — Documentation = "https://py.sdk.modelcontextprotocol.io/v2/" under [project.urls]
  • src/mcp-types/pyproject.toml:34 — the same URL for the mcp-types distribution
  • mkdocs.yml:7 — site_url: https://py.sdk.modelcontextprotocol.io/v2/

Why the pyproject entries are in scope for this PR. The PR description explains that it must merge last, right before the v2.0.0 tag, because README.md at the tagged commit is the PyPI long description — repo content at the tag becomes permanent PyPI artifacts. The [project.urls] Documentation entry ships in the 2.0.0 wheel metadata through exactly the same mechanism: it becomes the Documentation link in the PyPI project sidebar. The declared dependency on the docs-site-layout PR plausibly covers mkdocs.yml's site_url (that's docs-site configuration), but a site-layout PR would not touch package metadata in the two pyproject.toml files, and nothing in this PR's description assigns them elsewhere.

Concrete walk-through. (1) This PR merges as-is and v2.0.0 is tagged at that commit. (2) The release builds the mcp and mcp-types 2.0.0 wheels; both carry Project-URL: Documentation, https://py.sdk.modelcontextprotocol.io/v2/ in their METADATA. (3) PyPI renders the 2.0.0 page: the long description (this PR's README) links to https://py.sdk.modelcontextprotocol.io/ root URLs throughout, while the sidebar Documentation link on the same page points at /v2/. (4) The docs-site-layout PR (which per the stated merge order lands before this one) flips the site so v2 serves at the root and v1 moves to /v1/; whether /v2/ still resolves afterwards depends entirely on that PR keeping a redirect. (5) PyPI metadata for a released version is immutable, so if /v2/ ever stops resolving, the 2.0.0 sidebar link is permanently broken.

Why nothing else catches it. The pre-commit README-snippets check and the strict docs build that the PR cites as testing only cover Markdown and docs sources — neither inspects [project.urls] in the pyproject files or site_url in mkdocs.yml. The root cause is simply that the URL sweep was run over Markdown/YAML doc content and missed the TOML/config files.

Impact and fix. Nothing breaks functionally — the most likely outcome is a redirect or a merely inconsistent link — which is why this is a nit rather than blocking. But because the metadata is frozen at the tag, the fix is only cheap before tagging: update the two Documentation URLs in pyproject.toml and src/mcp-types/pyproject.toml to https://py.sdk.modelcontextprotocol.io/ in this PR (they follow the same at-the-tag logic as the README changes here). mkdocs.yml's site_url controls the built site's canonical URLs and sitemap; if the docs-site-layout PR doesn't already flip it, it should be updated too, but that one can reasonably be assigned to the layout PR.


## What is MCP?

Expand All @@ -41,10 +41,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

Expand Down Expand Up @@ -82,7 +82,7 @@

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

Expand Down Expand Up @@ -122,7 +122,7 @@
[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
Expand Down
17 changes: 11 additions & 6 deletions SECURITY.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
20 changes: 7 additions & 13 deletions docs/get-started/installation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
27 changes: 11 additions & 16 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,17 +23,12 @@
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
Expand Down Expand Up @@ -74,7 +69,7 @@
"run",
"--frozen",
"--with",
"mcp[cli]==2.0.0rc1",
"mcp[cli]==2.0.0",
"mcp",
"run",
"/absolute/path/to/server.py"
Expand All @@ -84,12 +79,12 @@
}
```

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.

Expand All @@ -107,7 +102,7 @@
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.
Expand All @@ -121,7 +116,7 @@
"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"]
}
}
}
Expand All @@ -139,7 +134,7 @@
"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"]
}
}
}
Expand All @@ -156,7 +151,7 @@
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.
Expand All @@ -174,8 +169,8 @@
## 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]" 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`) into `claude_desktop_config.json`, so you never have to.

Check warning on line 173 in docs/get-started/real-host.md

View check run for this annotation

Claude / Claude Code Review

Recap bullet missed the pin-caveat sweep in real-host.md 

The Recap bullet still says `mcp install` writes "that same command (plus the absolute path to `uv`)", but after this PR removed the pin from the launch command, "that same command" is the unpinned form — while `mcp install` still writes an exact pin (`mcp[cli]==2.0.0` in the page's own JSON example), so the Recap now contradicts the body's "three additions" enumeration two sections earlier. Mirror the body's caveat, e.g. "(plus the absolute path to `uv`, `--frozen`, and an exact version pin)".

@claude claude Bot Jul 27, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

🟡 The Recap bullet still says mcp install writes "that same command (plus the absolute path to uv)", but after this PR removed the pin from the launch command, "that same command" is the unpinned form — while mcp install still writes an exact pin (mcp[cli]==2.0.0 in the page's own JSON example), so the Recap now contradicts the body's "three additions" enumeration two sections earlier. Mirror the body's caveat, e.g. "(plus the absolute path to uv, --frozen, and an exact version pin)".

Extended reasoning...

What the bug is. The Recap bullet at docs/get-started/real-host.md:173 reads: "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." The referent "that same command" is the launch command in the bullet directly above (line 172), which this PR edited to the unpinned form uv run --with "mcp[cli]" mcp run .... But mcp install writes a pinned entry — the page's own JSON example (updated by this PR) shows mcp[cli]==2.0.0, and mcp_requirement() in src/mcp/cli/claude.py pins to the installed version. So the Recap now claims the written config differs from the typed command only by the uv path, which is false in exactly the dimension the PR's narrative centers on: you type the unpinned command, the tool adds the pin.

Why this is PR-introduced, not pre-existing. Before this PR, "that same command" was the pinned command (uv run --with "mcp[cli]==2.0.0rc1" ...), so the Recap sentence was accurate about the pin — the config entry really was that command plus the uv path (only --frozen was glossed over, a minor pre-existing simplification). This PR removed the pin from the launch command everywhere on the page, which changed what "that same command" means, and the pin caveat that used to live inside the command itself now has to live in the prose — but line 173 was never updated.

Why it contradicts the page's own body. The PR demonstrably swept this exact sentence pattern in the two parallel body sentences: "The launch command" section now ends "...so what you type by hand and what the tool generates agree, apart from the exact version pin the tool adds", and the Claude Desktop section was changed from "two additions" to "three additions: the absolute path to uv, --frozen ..., and an exact pin to the mcp version you have installed". The Recap bullet is the one instance of the pattern the sweep missed, so the Recap directly contradicts the body's enumeration two sections earlier on the same page.

Step-by-step proof.

  1. A reader reaches the Recap. Bullet 2 gives the command: uv run --with "mcp[cli]" mcp run /absolute/path/to/server.py (unpinned — the PR's edit).
  2. Bullet 3 says mcp install writes "that same command (plus the absolute path to uv)" — i.e., per the Recap, the only difference between what they type and what lands in claude_desktop_config.json is the uv path.
  3. They scroll up to the Claude Desktop section: the JSON entry shows --frozen and mcp[cli]==2.0.0, and the prose explicitly enumerates "three additions" including "an exact pin to the mcp version you have installed".
  4. The Recap's claim and the body's enumeration disagree about what mcp install writes — on the same page, about the same command.

One refutation angle considered: the Recap already omitted --frozen pre-PR, so one could argue it was always an intentional simplification. But the pin discrepancy is genuinely new with this PR (pre-PR, the pin lived inside "that same command", so the Recap was pin-accurate), and the PR fixed this exact sentence pattern in both body sections — the Recap is a missed spot in the sweep, not a deliberate summary style.

How to fix. One-clause edit mirroring the body's caveat, e.g.: "It writes that same command (plus the absolute path to uv, --frozen, and an exact version pin) into claude_desktop_config.json, so you never have to."

Severity. Nit: prose-only docs inconsistency, nothing breaks, and the docs site rebuilds from main so it stays cheaply fixable after the tag — but fixing it in this PR keeps the page self-consistent.

* **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
Loading
Loading