[v1.x] Move the v1.x docs to /v1/ and mark v1.x as the maintenance line

With v2 becoming the stable release, v1.x moves from the site root to
/v1/ and stops deploying the site itself: the combined site is built and
deployed from main, which builds this branch's docs into /v1/ via the
new scripts/docs/build.sh. A `docs` CI job runs that same script, so a
change that breaks the v1 docs fails on this branch rather than at
main's next deploy. site_url and the package's Documentation URL move to
/v1/ so canonical links, the sitemap, and llms.txt point at where these
pages are actually served.

The README and landing page now describe v1.x as the maintenance line
and send new users to the v2 docs, and every install line pins `mcp<2`
so a reader following these docs stays on the 1.x line now that an
unpinned install selects 2.x.

Author: maxisbey

.github/workflows/deploy-docs.yml

@@ -76,3 +76,20 @@ jobs:
 
       - name: Check doc snippets are up to date
         run: uv run --frozen scripts/update_doc_snippets.py --check
+
+  # The published site is built and deployed from main, which builds this
+  # branch's docs (via scripts/docs/build.sh) under /v1/; this branch has no
+  # deploy workflow of its own. This job runs that same script so a change
+  # that breaks the v1 docs fails here rather than at main's next deploy.
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+          version: 0.9.5
+
+      - name: Build docs
+        run: bash scripts/docs/build.sh

.github/workflows/shared.yml

@@ -13,11 +13,9 @@
 
 </div>
 
-> **This documents v1.x, the stable release line of the MCP Python SDK. v2 is in alpha.**
+> **This documents v1.x, the maintenance line of the MCP Python SDK.** v2 is the current stable release: `pip install mcp` now installs 2.x. See the [v2 documentation](https://py.sdk.modelcontextprotocol.io/) and the [migration guide](https://py.sdk.modelcontextprotocol.io/migration/) for what changed and how to upgrade.
 >
-> v2 pre-releases are published to PyPI as `2.0.0aN`. Installers never select a pre-release unless you opt in (for example `pip install mcp==2.0.0a1`), so v1.x users 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 v2 release lands.** See the [v2 documentation](https://github.com/modelcontextprotocol/python-sdk/blob/main/README.v2.md) and the [migration guide](https://github.com/modelcontextprotocol/python-sdk/blob/main/docs/migration.md) for what's changing.
->
-> v1.x remains recommended for production use. It is in maintenance mode and continues to receive critical bug fixes and security patches.
+> **Staying on v1.x?** Keep a `<2` upper bound on your requirement (for example `mcp>=1.28,<2`) so an unpinned resolve stays on the 1.x line. v1.x remains supported for existing deployments and continues to receive critical bug fixes and security patches; its documentation is at <https://py.sdk.modelcontextprotocol.io/v1/>.
 
 <!-- omit in toc -->
 ## Table of Contents
@@ -38,7 +36,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://modelcontextprotocol.github.io/python-sdk/
+[docs-url]: https://py.sdk.modelcontextprotocol.io/v1/
 [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
@@ -69,13 +67,13 @@ If you haven't created a uv-managed project yet, create one:
    Then add MCP to your project dependencies:
 
    ```bash
-   uv add "mcp[cli]"
+   uv add "mcp[cli]<2"
    ```
 
 Alternatively, for projects using pip for dependencies:
 
 ```bash
-pip install "mcp[cli]"
+pip install "mcp[cli]<2"
 ```
 
 ### Running the standalone MCP development tools
@@ -143,7 +141,7 @@ _Full example: [examples/snippets/servers/fastmcp_quickstart.py](https://github.
 You can install this server in [Claude Code](https://docs.claude.com/en/docs/claude-code/mcp) and interact with it right away. First, run the server:
 
 ```bash
-uv run --with mcp examples/snippets/servers/fastmcp_quickstart.py
+uv run --with "mcp<2" examples/snippets/servers/fastmcp_quickstart.py
 ```
 
 Then add it to Claude Code:
@@ -177,8 +175,8 @@ The [Model Context Protocol (MCP)](https://modelcontextprotocol.io) lets you bui
 - [Low-Level Server](docs/low-level-server.md) -- direct handler registration for advanced use cases
 - [Protocol Features](docs/protocol.md) -- MCP primitives, server capabilities
 - [Testing](docs/testing.md) -- in-memory transport testing with pytest
-- [API Reference](https://modelcontextprotocol.github.io/python-sdk/api/)
-- [Experimental Features (Tasks)](https://modelcontextprotocol.github.io/python-sdk/experimental/tasks/)
+- [API Reference](https://py.sdk.modelcontextprotocol.io/v1/api/)
+- [Experimental Features (Tasks)](https://py.sdk.modelcontextprotocol.io/v1/experimental/tasks/)
 - [Model Context Protocol documentation](https://modelcontextprotocol.io)
 - [Model Context Protocol specification](https://modelcontextprotocol.io/specification/latest)
 - [Officially supported servers](https://github.com/modelcontextprotocol/servers)

README.md

@@ -1,7 +1,9 @@
 # MCP Python SDK
 
-!!! tip "Looking for the upcoming v2?"
-    See the [v2 development documentation](https://py.sdk.modelcontextprotocol.io/v2/).
+!!! tip "You are viewing the v1.x maintenance-line documentation"
+    v2 is the current stable release: its documentation is at
+    <https://py.sdk.modelcontextprotocol.io/>. Staying on v1.x for now? Pin `mcp<2`
+    (for example `mcp>=1.28,<2`) so an unpinned install doesn't move you to 2.x.
 
 The **Model Context Protocol (MCP)** allows applications to provide context for LLMs in a standardized way, separating the concerns of providing context from the actual LLM interaction.
 
@@ -48,7 +50,7 @@ if __name__ == "__main__":
 Run the server:
 
 ```bash
-uv run --with mcp server.py
+uv run --with "mcp<2" server.py
 ```
 
 Then open the [MCP Inspector](https://github.com/modelcontextprotocol/inspector) and connect to `http://localhost:8000/mcp`:
@@ -74,5 +76,5 @@ Full API documentation is available in the [API Reference](api.md).
 ## llms.txt
 
 Reading with an LLM? This documentation is also published in the [llms.txt](https://llmstxt.org/) format:
-[llms.txt](https://py.sdk.modelcontextprotocol.io/llms.txt) is an index of the pages, and
-[llms-full.txt](https://py.sdk.modelcontextprotocol.io/llms-full.txt) contains every page in a single file.
+[llms.txt](https://py.sdk.modelcontextprotocol.io/v1/llms.txt) is an index of the pages, and
+[llms-full.txt](https://py.sdk.modelcontextprotocol.io/v1/llms-full.txt) contains every page in a single file.

docs/index.md

@@ -1,16 +1,18 @@
 # Installation
 
-The Python SDK is available on PyPI as [`mcp`](https://pypi.org/project/mcp/) so installation is as simple as:
+The Python SDK is available on PyPI as [`mcp`](https://pypi.org/project/mcp/). These docs describe the **v1.x maintenance line**;
+the `<2` bound keeps you on it now that `pip install mcp` selects the 2.x stable release by default (the
+[v2 documentation](https://py.sdk.modelcontextprotocol.io/) covers that line):
 
 === "pip"
 
     ```bash
-    pip install mcp
+    pip install "mcp<2"
     ```
 === "uv"
 
     ```bash
-    uv add mcp
+    uv add "mcp<2"
     ```
 
 The following dependencies are automatically installed:

docs/installation.md

@@ -5,7 +5,7 @@ strict: true
 repo_name: modelcontextprotocol/python-sdk
 repo_url: https://github.com/modelcontextprotocol/python-sdk
 edit_uri: edit/v1.x/docs/
-site_url: https://py.sdk.modelcontextprotocol.io/
+site_url: https://py.sdk.modelcontextprotocol.io/v1/
 
 # TODO(Marcelo): Add Anthropic copyright?
 # copyright: © Model Context Protocol 2025 to present

mkdocs.yml

@@ -91,7 +91,7 @@ bump = true
 
 [project.urls]
 Homepage = "https://modelcontextprotocol.io"
-Documentation = "https://py.sdk.modelcontextprotocol.io/"
+Documentation = "https://py.sdk.modelcontextprotocol.io/v1/"
 Repository = "https://github.com/modelcontextprotocol/python-sdk"
 Issues = "https://github.com/modelcontextprotocol/python-sdk/issues"
 

pyproject.toml

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+#
+# Build the v1.x documentation into ./site.
+#
+# This is the single build recipe for this branch's docs. The combined site
+# is assembled and deployed from main, which fetches this branch and runs this
+# script to build it under /v1/ (main's scripts/build-docs.sh picks
+# scripts/docs/build.sh from each branch it builds). The `docs` CI job on
+# this branch runs the same script, so what CI checks is what gets published.
+#
+# Usage:
+#   scripts/docs/build.sh
+#
+set -euo pipefail
+
+cd "$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+
+uv sync --frozen --group docs
+NO_MKDOCS_2_WARNING=1 uv run --frozen --no-sync mkdocs build --site-dir site