chore: pin mcp>=1.28.1,<2 ahead of MCP Python SDK v2 stable release

[Altamimi-Dev]

Pull Request

🔗 Related Issue

Closes #5839

---

📝 Summary

Adds a protective <2 upper bound to the mcp dependency across all first-party manifests ahead of the MCP Python SDK v2 stable release (targeted 2026-07-27/28), which is a major rework with pervasive breaking changes (FastMCP→MCPServer rename, mcp.types split-out, WebSocket transport removal). Every shipped manifest is bounded to mcp>=1.28.1,<2 and uv.lock is regenerated; resolution is unchanged and stays on the 1.28.x line. fastmcp needs no change — its own mcp dependency is intersected with our direct <2 pin, so our bound constrains the whole resolution.

The cookiecutter template (mcp-servers/templates/python/...) was also bounded (mcp>=1.0.0,<2) for consistency, keeping its lower floor. The v2 migration itself is explicitly out of scope per the issue — this is a purely protective packaging change.

---

📏 Reviewability

• This PR has one clear purpose
• The linked issue is not labeled triage
• Unrelated bugs or improvements are tracked in separate issues/PRs
• Tests are included with the code they validate
• If AI-assisted, I understand and can explain the generated changes

---

🏷️ Type of Change

• Bug fix
• Feature / Enhancement
• Documentation
• Refactor
• Chore (deps, CI, tooling)
• Other (describe below)

---

🧪 Verification

Check	Command	Status
Manifest sweep (exactly 8 bounded lines, none unbounded)	grep -rEn 'mcp(>=|==|~=|>)[0-9]' --include='*.toml' --include='*.txt' ...	✅ 8 lines, all ,<2
Lock regenerated	uv lock	✅ Resolved 376 packages
Lock — bounded specifier present	grep -c 'specifier = ">=1.28.1,<2"' uv.lock	✅ 1
Lock — mcp stays on 1.x	grep -A1 '^name = "mcp"$' uv.lock | grep version	✅ version = "1.28.1"
Runtime import smoke	uv sync --extra plugins && uv run python -c "import mcp, mcp.types; ..."	✅ mcp 1.28.1 OK
Unit tests	make test	✅ 20847 passed, 795 skipped, 2 xfailed

Only the resolved-graph metadata changed (mcp specifier); resolved package versions are identical, so the change is runtime-neutral today. Container build is covered by CI — the resolved graph is unchanged so the build cannot differ.

---

✅ Checklist

• Code formatted (make black isort pre-commit)
• Tests added/updated for changes
• Documentation updated (N/A — no docs reference the unbounded pin)
• No secrets or credentials committed

---

📓 Notes

uv.lock also shows deterministic byproduct churn from the repo's own exclude-newer-span = "P10D" config re-resolving on lock (an absolute exclude-newer timestamp and a couple of transitive marker refinements). No resolved package version changed.

[msureshkumar88]

E2E verification — real environment run

Checked out this PR's exact head commit locally (5839-pin-mcp-below-2 @ a6e7f1545) and ran the fix through the actual toolchain rather than just re-reading the diff.

Config: uv 0.10.2, Python 3.12.3, local checkout, --extra plugins resolve, live PyPI query (network confirmed reachable).

Commands + results:

1. grep -rEn '"mcp(>=|==|~=|>)[0-9]...' --include='*.toml' --include='*.txt' . — swept every first-party manifest. All 8 lines bounded ,<2 (7 at mcp>=1.28.1,<2, cookiecutter template at mcp>=1.0.0,<2). Zero unbounded mcp pins left in the tree.
2. uv lock --check — pass, uv.lock matches the manifests as committed, no drift.
3. uv sync --extra plugins — real dependency resolve/install against this PR's lock. Succeeded (376 packages resolved).
4. Runtime assertion (importlib.metadata.version("mcp")) — resolved to 1.28.1, < 2 holds. (Note: mcp.__version__ doesn't exist as a module attribute — used importlib.metadata instead.)
5. Live PyPI check (pypi.org/pypi/mcp/json) — latest published mcp right now is still 1.28.1; v2 stable hasn't landed yet as of this review, confirming the pin is precautionary/pre-emptive rather than already-broken — exactly the intended defensive posture ahead of the announced release window.
6. import fastmcp against the newly-bounded resolution — imports cleanly, confirming the PR's claim that fastmcp's own unbounded mcp dependency is safely intersected by the direct <2 pin without needing its own bound.

All 6 steps passed. Combined with this PR's already-green CI on the same commit (full make test, 20847 passed, container builds for all 4 architectures, dependency-review, DCO) this covers both the resolution behavior specific to this fix and the broader regression surface.

Review outcome: Approve

No blocking or functionally-impacting findings — the fix is minimal, matches every acceptance criterion in #5839, and verified to actually bound resolution as intended.

Two small optional, non-blocking follow-ups (not required for merge):

• pyproject.toml:124 — the other non-obvious pins in this file carry an inline comment (e.g. # Transitive pin (alembic)); a short one here (# <2: ahead of v2 stable, breaking changes — see #5839) would help future maintainers know when it's safe to lift.
• Worth opening a tracking issue for the eventual v2 migration / pin removal, referenced from here, so the bound doesn't quietly outlive its purpose once mcp 1.x stops getting patches.