Merge remote-tracking branch 'origin/main' into feat/experimental-server-card

Author: claude

.github/ISSUE_TEMPLATE/bug.yaml

@@ -11,13 +11,26 @@ body:
     id: checks
     attributes:
       label: Initial Checks
-      description: Just making sure you're using the latest version of MCP Python SDK.
+      description: >
+        Both the 2.x stable line and the 1.x maintenance line are supported, and only
+        the newest release of each line receives fixes.
       options:
-        - label: I confirm that I'm using the latest version of MCP Python SDK
+        - label: I confirm that I'm using the newest release of my line (the latest 2.x, or the latest 1.x if I'm still on v1)
           required: true
         - label: I confirm that I searched for my issue in https://github.com/modelcontextprotocol/python-sdk/issues before opening this issue
           required: true
 
+  - type: dropdown
+    id: release-line
+    attributes:
+      label: Release line
+      description: Which major version of the SDK are you using?
+      options:
+        - 2.x (current stable)
+        - 1.x (maintenance line, v1.x branch)
+    validations:
+      required: true
+
   - type: textarea
     id: description
     attributes:

.github/ISSUE_TEMPLATE/v2-feedback.yaml

@@ -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

.github/actions/conformance/expected-failures.yml

@@ -10,7 +10,23 @@
 # scenarios start passing and MUST be removed from this list (the runner fails
 # on stale entries), so the baseline burns down per milestone.
 
-client: []
+client:
+  # SEP-1932 (DPoP): the SDK's OAuth client does not implement DPoP proofs.
+  # The entries are per-check (conformance #406) because both scenarios
+  # pass their non-DPoP checks (discovery, token acquisition, request
+  # flow) live.
+  - auth/dpop:sep-1932-client-token-request-proof
+  - auth/dpop:sep-1932-client-dpop-auth-scheme
+  - auth/dpop:sep-1932-client-fresh-proof
+  - auth/dpop-nonce:sep-1932-client-token-request-proof
+  - auth/dpop-nonce:sep-1932-client-dpop-auth-scheme
+  - auth/dpop-nonce:sep-1932-client-fresh-proof
+  - auth/dpop-nonce:sep-1932-client-as-nonce
+  - auth/dpop-nonce:sep-1932-client-rs-nonce
+  # Workload identity federation: the OAuth client does not implement the
+  # urn:ietf:params:oauth:grant-type:jwt-bearer grant (it answers with
+  # authorization_code). Per-check for the same reason.
+  - auth/wif-jwt-bearer:wif-grant-type
 
 server:
   # SEP-2663 (io.modelcontextprotocol/tasks): the SDK does not implement the

.github/workflows/conformance.yml

@@ -15,21 +15,9 @@ permissions:
 
 env:
   # Pinned conformance harness package spec (passed verbatim to `npx --yes`).
-  # Use a published version, e.g. @modelcontextprotocol/conformance@0.2.0-alpha.7.
   # Bump deliberately and reconcile both
   # .github/actions/conformance/expected-failures*.yml files in the same change.
-  #
-  # Temporarily pinned to the pkg.pr.new build of conformance main@4944b268
-  # (0.2.0-alpha.8, which includes #372: fail checks whose prerequisite is
-  # missing instead of skipping them) — alpha.8 is not published to npm yet.
-  # Pinned by commit SHA so the tarball cannot move under us;
-  # CONFORMANCE_PKG_SHA256 pins the bytes and the fetch-and-verify step below
-  # downloads, checks the digest, and repoints CONFORMANCE_PKG at the
-  # verified local copy. Repin to the next published @modelcontextprotocol/
-  # conformance release (>=0.2.0-alpha.8) once it ships, then drop
-  # CONFORMANCE_PKG_SHA256 and the fetch-and-verify steps.
-  CONFORMANCE_PKG: "https://pkg.pr.new/@modelcontextprotocol/conformance@4944b268"
-  CONFORMANCE_PKG_SHA256: "0f70c035782d319d72ab427653c5275db5c50429d59fae0241a645b33aeda1a7"
+  CONFORMANCE_PKG: "@modelcontextprotocol/conformance@0.2.0-alpha.10"
 
 jobs:
   server-conformance:
@@ -45,19 +33,6 @@ jobs:
       - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
         with:
           node-version: 24
-      - name: Fetch and verify conformance harness
-        # Only when CONFORMANCE_PKG is a URL: download, check the recorded
-        # sha256, and re-point CONFORMANCE_PKG at the verified local tarball.
-        # When CONFORMANCE_PKG is a registry spec, this step is a no-op (npm's
-        # own integrity check applies).
-        run: |
-          case "$CONFORMANCE_PKG" in
-            https://*)
-              curl -fsSL "$CONFORMANCE_PKG" -o /tmp/conformance.tgz
-              echo "$CONFORMANCE_PKG_SHA256  /tmp/conformance.tgz" | sha256sum -c -
-              echo "CONFORMANCE_PKG=file:/tmp/conformance.tgz" >> "$GITHUB_ENV"
-              ;;
-          esac
       - run: uv sync --frozen --all-extras --package mcp-everything-server
       - name: Run server conformance (active suite)
         run: >-
@@ -117,19 +92,6 @@ jobs:
       - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
         with:
           node-version: 24
-      - name: Fetch and verify conformance harness
-        # Only when CONFORMANCE_PKG is a URL: download, check the recorded
-        # sha256, and re-point CONFORMANCE_PKG at the verified local tarball.
-        # When CONFORMANCE_PKG is a registry spec, this step is a no-op (npm's
-        # own integrity check applies).
-        run: |
-          case "$CONFORMANCE_PKG" in
-            https://*)
-              curl -fsSL "$CONFORMANCE_PKG" -o /tmp/conformance.tgz
-              echo "$CONFORMANCE_PKG_SHA256  /tmp/conformance.tgz" | sha256sum -c -
-              echo "CONFORMANCE_PKG=file:/tmp/conformance.tgz" >> "$GITHUB_ENV"
-              ;;
-          esac
       # --compile-bytecode: without it, ~40 concurrently spawned interpreters
       # race to byte-compile site-packages during the timing-sensitive window.
       - run: uv sync --frozen --all-extras --package mcp --compile-bytecode

.github/workflows/deploy-docs.yml

@@ -3,8 +3,10 @@ name: Deploy Docs
 on:
   push:
     branches:
+      # main is the sole deployer of the combined site (v2 at / and /v2/, v1.x
+      # at /v1/); the v1.x branch has no deploy workflow. A v1.x docs change is
+      # published by the next main deploy or a manual workflow_dispatch here.
       - main
-      - v1.x
     paths:
       - docs/**
       # docs pages include their code blocks from these files via `--8<--`, so a
@@ -48,7 +50,7 @@ jobs:
           enable-cache: true
           version: 0.9.5
 
-      - name: Build combined docs (v1.x at /, main at /v2/)
+      - name: Build combined docs (main at / and /v2/, v1.x at /v1/)
         run: bash scripts/build-docs.sh site
 
       - name: Configure Pages

.github/workflows/shared.yml

@@ -51,7 +51,7 @@ jobs:
       - name: mcp-types installs and imports standalone
         run: |
           uv run --isolated --no-project --with ./src/mcp-types python -c \
-            "import mcp_types, mcp_types.jsonrpc, mcp_types.methods, mcp_types.version, mcp_types.v2025_11_25, mcp_types.v2026_07_28"
+            "import mcp_types, mcp_types.jsonrpc, mcp_types.methods, mcp_types.version, mcp_types._v2025_11_25, mcp_types._v2026_07_28"
 
   test:
     name: test (${{ matrix.python-version }}, ${{ matrix.dep-resolution.name }}, ${{ matrix.os }})

AGENTS.md

@@ -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

CONTRIBUTING.md

@@ -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
 

README.md

@@ -13,18 +13,18 @@
 
 </div>
 
-> [!CAUTION]
-> **This README documents v2 of the MCP Python SDK — a pre-release (alpha/beta) line under active development. Do not use v2 in production.** Pre-releases are published to PyPI as `2.0.0aN` / `2.0.0bN`, and **each pre-release may 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://modelcontextprotocol.io/specification/2026-07-28) (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-27, 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).
 
 ## 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/).
 
 ## What is MCP?
 
@@ -41,10 +41,10 @@ Python 3.10+.
 ## Installation
 
 ```bash
-uv add "mcp[cli]==2.0.0b1"          # or: pip install "mcp[cli]==2.0.0b1"
+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.0b1"` 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
 
@@ -82,7 +82,7 @@ Call `add` with `a=1`, `b=2` and you get `3` back.
 
 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
 
@@ -122,7 +122,7 @@ This project is licensed under the MIT License. See the [LICENSE](https://github
 [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