Re-narrow the mcp pin to <2.0: the widened cap contradicts its own documented rationale #342

Decision taken 2026-08-07: re-narrow mcp from >=1.27,<3.0 back to >=1.27,<2.0. Filed so the decision is durable rather than living in a session transcript, and sequenced behind #338 because both touch uv.lock.

The concrete finding

pyproject.toml currently states the constraint and its justification in the same block, and they disagree with each other:

# Cap at <2.0 so a deliberate review happens before adopting
# any new major release. Bump the lower bound when verifying a
# newer release; bump the upper bound only after auditing the
# _compat shim against the new internals.
# 1.27.2 audited 2026-05-31: ...
"mcp>=1.27,<3.0",

The comment says <2.0. The pin says <3.0. #316 widened the constraint and left the rationale untouched, so the file now documents a guard it no longer has.

Why the guard exists

src/hive/_compat.py monkey-patches private attributes on mcp.shared.session.RequestResponder — _completed, _on_complete, _entered, _cancel_scope, respond. Private internals carry no compatibility promise across a major release. The narrow cap existed precisely so that adopting mcp 2.x required a human to audit the shim first.

<3.0 admits the entire 2.x line — the exact major boundary the original cap was written to exclude. The shim is self-gated and degrades quietly if the symbols vanish, which is a real mitigation but the wrong one to rely on: quiet degradation means the cancel-race crash returns without a failing build to announce it.

Scope

• pyproject.toml: mcp>=1.27,<3.0 -> mcp>=1.27,<2.0.
• Refresh uv.lock for the narrowed specifier. Note uv.lock already records >=1.27,<3.0, so the two currently agree and no pre-existing drift is being carried.
• While in that block: the rationale comment still points at python-sdk#2610 as the upstream tracker. The correct one is #2416 — see Drop _compat.py: if mcp/python-sdk#2610 still silent on 2026-06-12, port the fix as our own upstream PR — due 2026-06-12 #127. AGENTS.md was corrected in docs: correct the compat-shim description in AGENTS.md #336; this comment was missed.

Sequencing

Blocked on #338 merging. That PR rewrites uv.lock for the cryptography 50 bump; its diff does not touch the mcp specifier line, so the conflict risk is modest, but regenerating the same lock from two branches invites avoidable churn.

Refs #316, #127, #336.