MCP Python SDK v2 Beta Drops June 30 — Pin mcp<2 in Your Dependency File Today

TL;DR: The MCP Python SDK v2 beta arrives June 30 and stable v2 ships July 27 — add mcp>=1.27,<2 to your pyproject.toml today or an auto-upgrade will break your MCP server when v2 lands.

The MCP project is on a tight release calendar: the alpha (v2.0.0a1) landed June 11, beta drops June 30 (four days from now), and v2.0.0 stable ships July 27 — one day before the July 28 spec lock. If you maintain a Python MCP server and you're not pinned, pip install --upgrade mcp or uv sync after July 27 will pull v2 automatically.

The one action to take today

In pyproject.toml:

[project]
dependencies = [
    "mcp>=1.27,<2",    # v2 beta drops June 30; pin until tested
]

Or in requirements.txt:

mcp>=1.27,<2

v1.x continues receiving critical fixes until a post-stable support window ends, so pinning <2 doesn't mean you stop getting security patches — it just holds your production install at a known-good version while you migrate on your schedule.

What actually breaks in v2

The headline change is a stateless protocol core: the initialize/initialized handshake and Mcp-Session-Id header are gone. Two new required HTTP headers (Mcp-Method, Mcp-Name) must be sent on every Streamable HTTP request. One error code moves (-32002 → -32602). List responses now carry ttlMs and cacheScope for client-side caching.

The June 17 post covered all four breaking changes in detail, with TypeScript migration examples. If you use the Python SDK's built-in transports (the common case), the SDK handles the header changes for you — the bigger break is any code that manually inspects session IDs or matches on error code -32002.

Test against the alpha now

pip install "mcp==2.0.0a1"   # install alpha in a separate venv
python -m pytest              # run your test suite against the new version

The SDK v2 alpha is functionally close to what the beta will ship — catching failures now beats catching them after July 27.

Sources: MCP Python SDK — GitHub | mcp — PyPI | MCP v2 Alpha: The July 28 Protocol Shift — Context Studios