modelcontextprotocol · maxisbey · Jul 29, 2026 · Aug 10, 2026 · Aug 14, 2026 · Aug 14, 2026
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -48,10 +48,25 @@ Bug fixes for clear, reproducible issues are welcome—but still create an issue
 | [`help wanted`](https://github.com/modelcontextprotocol/python-sdk/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22) | Experienced contributors | Maintainers probably won't get to this |
 | [`ready for work`](https://github.com/modelcontextprotocol/python-sdk/issues?q=is%3Aopen+is%3Aissue+label%3A%22ready+for+work%22) | Maintainers | Triaged and ready for a maintainer to pick up |
 
-Issues labeled `needs confirmation` or `needs maintainer action` are **not** ready for work—wait for maintainer input first.
+Issues labeled `needs confirmation` or `needs maintainer` are **not** ready for work—wait for maintainer input first.
 
 Before starting, comment on the issue so we can assign it to you. This prevents duplicate effort.
 
+## Issue Triage
+
+Every new issue gets a first look from a maintainer within two business days. That first look is the *triage*: it means labeling the issue and deciding whether it is valid and actionable, not fixing it.
+
+The core labels follow the shared [MCP SDK taxonomy](https://modelcontextprotocol.io/community/sdk-tiers#issue-triage-labels) (the repository also carries workflow labels of its own, such as `needs maintainer` and `needs decision`): one **type** (`bug`, `enhancement`, `question`), one **status** (`needs confirmation`, `needs repro`, `ready for work`, `good first issue`, `help wanted`), and — once actionable — one **priority**:
+
+| Label | Meaning | Commitment |
+|-------|---------|------------|
+| `P0` | Critical: core functionality failures (connections, message exchange, tools/resources/prompts) or a High/Critical-severity security issue | resolved within 7 days |
+| `P1` | Significant bug affecting many users | next release |
+| `P2` | Moderate issue or valuable feature request | as capacity allows |
+| `P3` | Nice-to-have or rare edge case | opportunistic |
+
+Security reports do not belong in the issue tracker; [SECURITY.md](SECURITY.md) has the private channel.
+
 ## Development Setup
 
 1. Make sure you have Python 3.10+ installed
@@ -125,6 +140,7 @@ pre-commit run --all-files
 - Follow PEP 8 style guidelines
 - Add type hints to all functions
 - Include docstrings for public APIs
+- Changing a dependency's version bound or adding a runtime dependency follows the [Dependency Policy](DEPENDENCY_POLICY.md)
 
 ## Pull Requests
 

diff --git a/DEPENDENCY_POLICY.md b/DEPENDENCY_POLICY.md
@@ -0,0 +1,26 @@
+# Dependency Policy
+
+`mcp` is a library that lives inside other people's environments, so its dependency requirements are chosen to constrain your resolver as little as possible while still describing what the SDK actually needs.
+
+## How requirements are declared
+
+* **Floors, not pins.** Every runtime dependency is a `>=` lower bound, set to the oldest version that provides what the SDK uses. There are no upper bounds unless a dependency's next major version is known to break the SDK.
+* **The one exception is `mcp-types`.** The wire-types package is developed and released with `mcp` in lockstep, so `mcp` requires exactly its own version (`mcp-types==<same version>`). It is not an independent constraint on your environment; it is the other half of the SDK.
+* **Environment markers instead of parallel packages** — Python-version and platform differences (`python_version`, `sys_platform`) are expressed as markers on the requirement, so one wheel serves every supported environment.
+* **Add-on tooling is an extra.** The command-line tooling and rich console output live behind extras (`mcp[cli]`, `mcp[rich]`); the client, the server, the HTTP transport stack, and auth support are all part of the base install by design.
+
+## When a floor moves
+
+A minimum version is raised only when the SDK starts relying on functionality, a fix, or an API that first appeared in that version. It is not raised because a dependency published a security advisory. The `>=` bound already lets — and expects — you to run the newest release your other constraints allow, so a higher floor would only shrink the set of environments the SDK installs into without changing what any correctly-updated environment resolves to. The SDK also does not add code to work around a vulnerability in a dependency; the fix belongs upstream and in your lockfile. ([Background](https://github.com/Kludex/uvicorn/discussions/2643) on this stance from another library that adopted it, and [python-sdk#1552](https://github.com/modelcontextprotocol/python-sdk/issues/1552).)
+
+The floors are also tested continuously rather than only when they are set: CI runs the test suite against a `lowest-direct` resolution as well as the locked set, on every supported Python version.
+
+Raising a floor is a minor-release change, called out in the release notes; the [versioning policy](https://py.sdk.modelcontextprotocol.io/versioning/) is the authority on what may ship in which kind of release. Adding a new required runtime dependency, or moving an existing one to its next major version, is a maintainer decision made in an issue before the pull request, not a side effect of a feature.
+
+## Automated updates
+
+[Dependabot](https://github.com/modelcontextprotocol/python-sdk/blob/main/.github/dependabot.yml) opens monthly, grouped pull requests for the `uv` lockfile and for GitHub Actions, with a 14-day cooldown on newly published versions. These refresh the versions the SDK is developed and tested against (`uv.lock`); they never change the requirements published to PyPI, which move only under the rules above.
+
+## Security in the SDK itself
+
+Vulnerabilities in the SDK's own code — as opposed to its dependencies — follow the reporting process in [SECURITY.md](https://github.com/modelcontextprotocol/python-sdk/blob/main/SECURITY.md).
diff --git a/RELEASE.md b/RELEASE.md
@@ -2,10 +2,17 @@
 
 ## Bumping Dependencies
 
+[`DEPENDENCY_POLICY.md`](DEPENDENCY_POLICY.md) says *when* a bound should
+move; this is the mechanics.
+
 1. Change the dependency version in `pyproject.toml`. The root `mcp` project's
    runtime dependencies are dynamic and live under
    `[tool.hatch.metadata.hooks.uv-dynamic-versioning].dependencies`.
-2. Upgrade lock with `uv lock --resolution lowest-direct`
+2. Regenerate the lock with `uv lock` (or `uv lock --upgrade-package <package>`
+   to move just that package's locked version). The committed `uv.lock` is a
+   normal, newest-allowed resolution; the `lowest-direct` resolution that
+   proves the floors still work is applied only by its CI matrix leg at test
+   time and is never committed.
 
 ## Release lines
 
@@ -104,8 +111,9 @@ hand for the same reason as above. Then ask someone to review the release.
 Pre-releases of the next version are cut from `main` with a PEP 440
 pre-release tag: `aN` for alphas, later `bN`/`rcN` for betas and release
 candidates. The PEP 440 suffix is what keeps `pip install mcp` on the stable
-version — installers only select a pre-release when it is requested explicitly (an
-exact pin, a specifier that names a pre-release version, or `--pre`).
+version — installers select a pre-release only when it is requested explicitly (an
+exact pin, a specifier that names a pre-release version, or `--pre`) or when no
+final release satisfies the requirement at all.
 
 1. During a pre-release phase the README and docs pin the exact pre-release
    version, so update those examples first (grep the outgoing version — the

diff --git a/docs/roadmap.md b/docs/roadmap.md
@@ -0,0 +1,34 @@
+# Roadmap
+
+The SDK's job is to implement the MCP specification, so its roadmap is organized by specification revision: one GitHub project board per revision, each item an issue or pull request you can follow. This page names the board that is current, what remains open on it, and the maintenance stance for the previous major.
+
+## The 2026-07-28 revision — shipped, with follow-ups
+
+v2 implements the [2026-07-28 specification](https://modelcontextprotocol.io/specification/2026-07-28) (and negotiates back to every earlier revision — see [Protocol versions](protocol-versions.md)); **[What's new in v2](whats-new.md)** is the tour of what that meant for the SDK.
+
+* Board: **[python-sdk · 2026-07-28 spec](https://github.com/orgs/modelcontextprotocol/projects/42)**, tracking issue [#2891](https://github.com/modelcontextprotocol/python-sdk/issues/2891).
+* Cross-SDK view: [2026-07-28 Spec Implementation](https://github.com/orgs/modelcontextprotocol/projects/41) tracks the same revision across all official SDKs.
+
+Open on that board:
+
+* **Capabilities API and the `server/discover` handler** — the last core item still in progress ([#2896](https://github.com/modelcontextprotocol/python-sdk/issues/2896)).
+
+## Extensions and optional client auth not yet implemented
+
+The 2026-07-28 revision moved some functionality out of the core protocol into named extensions, and defines client-side auth mechanisms an SDK may support. The ones this SDK does not implement yet are tracked as the entries in the conformance suite's expected-failures baseline, [`.github/actions/conformance/expected-failures.yml`](https://github.com/modelcontextprotocol/python-sdk/blob/main/.github/actions/conformance/expected-failures.yml) — that file is grouped by SEP and each entry is removed as the corresponding work lands, so it is the live burn-down list:
+
+* **Tasks extension** (`io.modelcontextprotocol/tasks`, [SEP-2663](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/seps/2663-tasks-extension.md)) — deferred at 2.0 because the 2026-07-28 design is wire-incompatible with the earlier in-core Tasks; tracked in [#2806](https://github.com/modelcontextprotocol/python-sdk/issues/2806).
+* **DPoP-bound access tokens** ([SEP-1932](https://github.com/modelcontextprotocol/modelcontextprotocol/issues/1932)) in the OAuth client.
+* **The workload-identity `jwt-bearer` grant** in the OAuth client.
+
+None of these blocks a release — each is carried as an expected failure in that baseline until it lands — but each is a real gap for anyone who needs the feature, and together they are the current queue.
+
+## Continuous work
+
+* **Conformance** — every pull request and every push to `main` runs the [conformance suite](https://github.com/modelcontextprotocol/conformance) as both server and client, against the released revisions and against the 2026-07-28 wire specifically; adopting each new harness release and reconciling its baseline is routine.
+* **The next specification revision** — draft-only wire changes are tried behind the draft protocol version before they are final, and land in a release once the revision ships; the SDK targets releasing support alongside each new specification version.
+* **Everything else** — the [issue tracker](https://github.com/modelcontextprotocol/python-sdk/issues) is the source of truth for bugs and smaller features; `P0`–`P3` labels carry priority.
+
+## The previous major
+
+`v1.x` is a maintenance line: critical bug fixes and security fixes only, no new features. Its documentation stays available at [/v1/](https://py.sdk.modelcontextprotocol.io/v1/), the support terms are in [Versioning and support policy](versioning.md#supported-release-lines), and the path off it is the **[Migration Guide](migration.md)**.
diff --git a/docs/versioning.md b/docs/versioning.md
@@ -0,0 +1,77 @@
+# Versioning and support policy
+
+This page states what a version number of the `mcp` package promises you: which changes can arrive in a minor release, which are held for the next major, how deprecations are announced, and how long each release line is supported.
+
+## The version number
+
+Releases follow [Semantic Versioning](https://semver.org/) semantics, written in [PEP 440](https://peps.python.org/pep-0440/) syntax:
+
+* **`2.X.Y`** — the version comes from the git tag; there is no version field to edit.
+* **`X` (minor)** — new functionality and every non-breaking change.
+* **`Y` (patch)** — bug fixes only.
+* **The leading `2` (major)** — the only place a breaking change to the public API can land.
+* **Pre-releases** are cut from `main` as `2.X.YaN` (alpha), `2.X.YbN` (beta), and `2.X.YrcN` (release candidate). Installers prefer final releases by default (PEP 440's [pre-release handling](https://peps.python.org/pep-0440/#handling-of-pre-releases)), so an unpinned `pip install mcp` stays on a stable release whenever one satisfies your requirement; you get a pre-release by asking for one, for example with an exact pin or `--pre`.
+
+`mcp` and its wire-types package [`mcp-types`](https://pypi.org/project/mcp-types/) release in lockstep at the same version: each `mcp` release requires exactly the matching `mcp-types` (`mcp-types==2.X.Y`).
+
+## What the public API is
+
+The compatibility promise covers the public API:
+
+* every name exported by `mcp` (its `__all__`) and by `mcp_types`,
+* the import paths, classes, functions, and parameters documented on this site and in the [API Reference](api/mcp/index.md),
+* documented behavior of those APIs.
+
+It does not cover names beginning with an underscore, modules and attributes that appear nowhere in the documentation, or the exact text of log lines, warnings, and exception messages (their *type* and the documented conditions that raise them are covered; their wording is not). Depending on one of those is depending on an implementation detail that may change in any release.
+
+Two labels mark APIs that sit outside the promise while they settle:
+
+* **Provisional** — shipped and supported, but the signature or semantics may still change in a minor release. The middleware chain and the `Dispatcher` lifecycle are examples; each is labelled provisional in its own documentation.
+* **Experimental** — behind an explicit opt-in and expected to change; treat it as a preview.
+
+## What counts as a breaking change
+
+These wait for the next major version:
+
+* removing or renaming a public name,
+* changing a signature so that a call that worked stops working (a removed or reordered parameter, a newly required argument, a narrowed accepted type),
+* changing a return type, a raised exception type, or documented behavior in a way existing callers would notice,
+* removing a documented import path, extra, or CLI command.
+
+These do not, and can ship in a minor release:
+
+* new functions, parameters with defaults, classes, fields, and enum members,
+* changes to provisional or experimental APIs,
+* new deprecation warnings, and the eventual removal of a protocol feature the specification has retired (see [Deprecations](#deprecations)),
+* raising a dependency's minimum version when the SDK needs newer functionality (see the [dependency policy](https://github.com/modelcontextprotocol/python-sdk/blob/main/DEPENDENCY_POLICY.md)), as long as the dependency's own changes do not reach you through the SDK's public API — if they would, the rules above apply — or dropping a Python version that upstream has ended support for; both are called out in the release notes,
+* bug fixes, including fixes that make the SDK match documented or specified behavior it should have had all along.
+
+When a fix is arguably both a bug fix and a behavior change, the deciding question is whether reasonable code written against the *documented* behavior breaks. If it does, the change is breaking.
+
+## Deprecations
+
+There are two kinds, warned differently on purpose.
+
+**SDK API deprecations** — a name or parameter this SDK is retiring. It is deprecated before it is removed: it keeps working for at least one minor release, marked wherever Python can carry a marker — callables and classes get [`typing_extensions.deprecated`](https://typing-extensions.readthedocs.io/en/latest/#typing_extensions.deprecated), which static type checkers flag and which warns at runtime; things that cannot carry one, such as module-level constants, are deprecated in their docstring and the migration guide — and it is removed only in a major version: something deprecated during 2.x is not removed before 3.0.
+
+**Protocol deprecations** — a feature the MCP specification has retired (for example the SEP-2577 set in the 2026-07-28 revision). The SDK keeps implementing these through the specification's deprecation window, and deprecation warnings for them use `MCPDeprecationWarning`, a `UserWarning` subclass, so they show by default rather than being hidden the way `DeprecationWarning` is outside `__main__`. Whether a retired feature can still do anything on a given connection depends on the protocol revision that connection negotiated; **[Deprecated features](deprecated.md)** and **[Serving legacy clients](run/legacy-clients.md)** describe the behavior, the replacements, and how to silence the warning when you genuinely serve older clients.
+
+## Supported release lines
+
+Two lines are maintained, and only the newest release of a line receives fixes:
+
+| Line | Branch | Receives |
+| --- | --- | --- |
+| 2.x — current stable | `main` | bug fixes, security fixes, new features |
+| 1.x — maintenance | [`v1.x`](https://github.com/modelcontextprotocol/python-sdk/tree/v1.x) | critical bug fixes and security fixes |
+
+Older 1.x releases and all pre-releases are unsupported. The security-specific version of this table, and how to report a vulnerability, is in [SECURITY.md](https://github.com/modelcontextprotocol/python-sdk/blob/main/SECURITY.md). Still on 1.x? Its documentation is at [/v1/](https://py.sdk.modelcontextprotocol.io/v1/), and a `<2` upper bound on your `mcp` requirement keeps an unpinned resolve on that line until you migrate.
+
+Python versions are supported from the version in the package's `requires-python` up to the newest CPython release the test suite runs against; support for a Python version ends only after that version's upstream end-of-life.
+
+## Where changes are announced
+
+* **Release notes** — every release publishes curated notes on [GitHub Releases](https://github.com/modelcontextprotocol/python-sdk/releases): highlights, anything known-incomplete, and a full change list. Pre-releases say what changed since the previous pre-release.
+* **The migration guide** — every breaking change between majors is documented in **[Migration Guide](migration.md)** with before-and-after code; a change is not merged for a major release without its entry.
+* **The `breaking change` label** — pull requests that make a breaking change carry it, so the set is queryable ahead of a major release.
+* **Deprecations** — as above, at least one minor release of deprecation before an SDK API is removed.
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -69,6 +69,9 @@ nav:
       - MCP Apps: advanced/apps.md
   - Troubleshooting: troubleshooting.md
   - Migration Guide: migration.md
+  - About:
+      - Versioning and support policy: versioning.md
+      - Roadmap: roadmap.md
   - API Reference: api/
 
 theme: