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

[maxisbey]

The README, the get-started docs, the What's new page, SECURITY.md, and the contributor docs all still describe v2 as a pre-release: pin an exact 2.0.0b1, "do not use in production," "v1.x is the only stable line." This flips that framing for the stable release. It is intended to merge last, right before the v2.0.0 tag, because README.md at the tagged commit is the PyPI long description.

Motivation and Context

At the stable release, pip install mcp installs 2.x, so the pre-release guidance inverts: the pin warnings that told readers "unpinned gives you v1.x" become false, and the caution banner would ship inside 2.0.0's PyPI page.

Changes:

• README: the pre-release caution block becomes a short stable-line note (with the "coming from v1" pointers and the <2 bound for projects not ready to migrate); the install line becomes plain mcp[cli]; doc links use the site root.
• docs: index.md, installation.md, and real-host.md lose their beta admonitions and version pins (the launch-command page keeps only the exact pin that mcp install itself writes); whats-new.md drops its beta note and two stale "since 2.0.0bN" provenance markers (one of which named 2.0.0b3, a version that will never exist); a one-line tense fix in migration.md.
• SECURITY.md gains a supported-versions table (2.x current, 1.28.x maintenance, older and pre-releases unsupported).
• AGENTS.md and CONTRIBUTING.md describe main as the stable line and v1.x as the maintenance branch; the v2 feedback issue template drops its pre-release wording and the v2-alpha label.

Reviewer attention on wording: SECURITY.md leaves the v1.x maintenance horizon open-ended (no end date); the README still links the spec release-candidate blog post, to be swapped for the final release post once that URL exists; mcp>=1.28,<2 is the example bound used throughout.

Depends on: #3176 (root doc links resolve to v2 only after the layout flips) and #3179 (so AGENTS.md's pointer to RELEASE.md is not stale). Merge order for release day: layout PRs, then this, then the tag.

How Has This Been Tested?

Docs-only. Pre-commit's README-snippets check passes; the strict docs build runs in CI.

Breaking Changes

None.

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update

Checklist

• I have read the MCP Documentation
• My code follows the repository's style guidelines
• New and existing tests pass locally
• I have added appropriate error handling
• I have added or updated documentation as needed

AI disclosure

AI assistance was used to draft and validate this change; I reviewed the result and take responsibility for it.

_{AI Disclaimer}

[github-actions]

📚 Documentation preview

Preview	https://pr-3178.mcp-python-docs.pages.dev
Deployment	https://204873eb.mcp-python-docs.pages.dev
Commit	59c066d
Triggered by	@maxisbey
Updated	2026-07-26 10:34:38 UTC

[cubic-dev-ai]

No issues found across 10 files

_{Re-trigger cubic}

[claude]

Beyond the inline nits, I also checked the new AGENTS.md pointer to RELEASE.md: at this commit RELEASE.md still says stable releases are cut from v1.x, but the PR description declares the RELEASE.md-update PR as a merge-order dependency, so that is a release-day sequencing item rather than a defect in this diff.

Extended reasoning...

Both inline findings were verified against the repository (the stale pre-release wording in docs/advanced/middleware.md and the remaining /v2/ URLs in the two pyproject.toml files and mkdocs.yml). The one additional concern examined was the AGENTS.md reference to RELEASE.md, whose current content contradicts this PR's branching-model text; it was ruled out because the PR explicitly depends on a separate RELEASE.md PR merging first. Not approving: the findings are nits, but this is the release-day framing flip with strict merge-order dependencies and author-flagged wording decisions (SECURITY.md support horizon, spec blog link swap) that warrant a maintainer's eye on timing and policy.

[claude]

🟡 The pre-release-tense sweep missed docs/advanced/middleware.md (line 9), a published docs page (Advanced > Middleware in the mkdocs nav) that still says "The signature and semantics are expected to change before v2 is final." Once this PR merges and v2.0.0 is tagged, the stable docs site promises API changes before a release that has already happened. Reword to post-stable framing (e.g. "may change in a future release"), keeping the provisional label the way this PR's whats-new.md edit does.

Extended reasoning...

What the bug is. This PR's stated purpose is to present v2 as the stable release "across the README, docs, and policies," and it systematically removes every pre-release-tense framing from the pages it touches — including the whats-new.md admonition anchored here, which now declares "v2 is the stable line." But docs/advanced/middleware.md line 9 was missed. Its warning admonition still reads:

Server.middleware is marked provisional in the source. The signature and semantics are expected to change before v2 is final.

Why this page matters. docs/advanced/middleware.md is in the published docs nav (mkdocs.yml, Advanced > Middleware), so it ships on the stable docs site. This PR is explicitly described as the last merge before the v2.0.0 tag — so the sentence becomes factually wrong the moment the PR achieves its purpose: it promises API changes "before" a release that, at that point, has already happened.

Why the PR creates the inconsistency. Before this PR, "before v2 is final" was accurate — v2 was in beta and the docs said so everywhere. After this PR, every other page says v2 is stable (docs/index.md, whats-new.md, README, installation docs), and the middleware page alone contradicts that framing. The PR even performed exactly this class of fix elsewhere: it reworded a tense in docs/migration.md ("with a v2 pre-release installed" → "while v2 was in pre-release") and its whats-new.md edit shows the intended pattern — keep the "deliberately marked provisional" label for middleware while dropping the beta-timeline language.

Why existing checks don't catch it. The strict mkdocs build and pre-commit checks validate links, snippets, and formatting — not temporal accuracy of prose. And the PR's sweep evidently targeted version pins (2.0.0bN) and /v2/ URLs, which this sentence contains neither of; only a grep for phrases like before v2 is final finds it.

Step-by-step proof.

1. This PR merges; per its description, v2.0.0 is tagged immediately after — v2 is now final.
2. The docs site rebuilds from main. docs/whats-new.md says "v2 is the stable line"; docs/index.md says "This documents v2, the current stable release line."
3. A reader evaluating middleware opens Advanced > Middleware and reads: "The signature and semantics are expected to change before v2 is final."
4. v2 is final, so the sentence either reads as a promise about a deadline that already passed, or misleads the reader into thinking v2 hasn't shipped yet — directly contradicting steps 2's framing.

How to fix. One-line reword keeping the provisional status but dropping the pre-release timeline, e.g.: "The signature and semantics may change in a future release." (For completeness: examples/stories/middleware/README.md carries similar "planned before beta" / "before v2 final" wording, but the examples/stories/ READMEs are internal dev notes full of TODO(maxisbey) markers, not published docs, and were clearly never in this sweep's scope — the published middleware.md page is the actionable miss.)

Severity. Nit: prose-only, nothing breaks, and unlike the PyPI long description the docs site rebuilds from main, so it's trivially fixable post-tag — but fixing it in this PR keeps the sweep complete.

(Note: the bug tracker anchors this comment to docs/whats-new.md lines 7–10 because the tracker requires a file in the diff; the actual stale text is at docs/advanced/middleware.md:8-9.)

[claude]

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