🟡 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.

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.

🟡 The docs' one remaining exact pin — the mcp[cli]==2.0.0 in this page's example of what mcp install writes — has no process to keep it current: the new RELEASE.md (#3179) states the stable line's docs "carry no version pin" and that routine stable releases need no pin-flip commit, and its grep step naming this file applies only during pre-release phases. From v2.0.1 on the published example will show the tool writing ==2.0.0 while it actually writes the installed version; a one-line fix either side closes the gap (genericize the pin, e.g. mcp[cli]==<installed version>, or add this line to RELEASE.md's stable-release checklist).

What the bug is. This PR deliberately keeps exactly one literal version pin in the docs: the "mcp[cli]==2.0.0" at docs/get-started/real-host.md:72, inside the JSON block showing the entry mcp install writes into claude_desktop_config.json (the PR description: "the launch-command page keeps only the exact pin that mcp install itself writes"). The problem is not the value 2.0.0 — it is that no process now exists to keep it current. This PR's declared dependency #3179 (landed as 68ca87e) rewrote RELEASE.md, and its "Stable release from main" section (RELEASE.md:36-38) states: "The stable line's README and docs carry no version pin (pip install \"mcp[cli]\" installs the newest stable release), so a routine stable release needs no pin-flip commit." That premise is contradicted by this page's one pin, and the step that does grep for pins in docs/get-started/real-host.md (RELEASE.md:110-116) applies only "During a pre-release phase" — it even says "the stable phase drops the pins."

The code path / concrete trigger. src/mcp/cli/claude.py (_mcp_requirement) pins the generated config entry to the installed version: on 2.0.1 it writes mcp[cli]==2.0.1. The docs site rebuilds from main on every push (deploy-docs.yml), and per the new RELEASE.md a routine stable release is tag-only with no doc commit.

Step-by-step proof. (1) v2.0.1 ships; per RELEASE.md's stable-release section, no pin-flip commit is made — the releaser is explicitly told none is needed. (2) The docs rebuild from main; real-host.md still shows "mcp[cli]==2.0.0" under the heading "This is the entry it writes." (3) A user on 2.0.1 runs uv run mcp install server.py; their claude_desktop_config.json contains mcp[cli]==2.0.1, diverging from the page's example, and the gap widens by one version with every release. (4) Nothing catches it: the fenced JSON block carries no snippet-source marker, and the strict docs build validates links, not version strings.

Why this is a nit, not blocking. One verifier refutation argued this is intentional behavior with no concrete failure, and it is largely right about impact: the JSON block is an illustrative sample full of placeholders (Bookshop, /absolute/path/to/uv), the prose at lines 82 and 173 explicitly describes the pin as "an exact pin to the mcp version you have installed," and line 31 already carves out the exception ("...agree, apart from the exact version pin the tool adds") — so a reader whose config shows 2.0.3 is not misled into any broken state, and even copying ==2.0.0 verbatim installs a valid stable release. Where the refutation undersells it is the process gap: the intentional design decision was "keep the one pin the tool itself writes," but the companion RELEASE.md rewrite then asserted the docs carry no pin and built the stable-release checklist on that false premise. The two landed PRs are inconsistent with each other, and the result is guaranteed, unbounded, uncaught drift in the one doc example whose whole point is showing exactly what the tool generates. That's worth a one-line fix, not a merge block.

How to fix (one line either side). Either genericize the example so it cannot rot — e.g. "mcp[cli]==<installed version>" (the surrounding prose already explains the pin in exactly those terms) — or amend RELEASE.md's "Stable release from main" section to name docs/get-started/real-host.md:72 as the one pin to bump per release.

Not a duplicate. The cubic-dev-ai comment on this page (addressed in 43e7743) was about qualifying the Recap's pin promise for source builds; the earlier RELEASE.md finding targeted the old, pre-#3179 text that no longer exists. This finding is about the new RELEASE.md's pin-free claim versus the pin this PR keeps.