Problem

docs/migration.md is a one-way guide: it tells you what to change once you move to 2.x. It has no guidance for the case where you cannot hard-cut, which is the situation of anyone maintaining a published MCP server or library while the ecosystem is split across both majors.

Concretely: the day 2.0.0 shipped, fresh installs of our published servers started resolving mcp==2.0.0 and crashed at import (ModuleNotFoundError: No module named 'mcp.server.fastmcp'), while existing users were still on 1.x. The realistic fix for a package author in that window is not "migrate", it is "support both majors for a transition period". I could not find a recipe for that anywhere in docs/.

What we ended up doing

Running in production since late July on two registry-listed servers (data-profiler-mcp, acb-tax-mcp):

try:
    # MCP SDK 2.x: FastMCP was renamed to MCPServer and the module moved.
    from mcp.server.mcpserver import MCPServer as FastMCP
except ImportError:
    # MCP SDK 1.x keeps the original path.
    from mcp.server.fastmcp import FastMCP

together with:

• a dependency pin of mcp>=1.2.0,<3 so installs may resolve either major, and
• a dedicated CI job that force-installs "mcp>=1.2.0,<2" and re-runs the test suite, so the 1.x fallback path stays tested while the main matrix resolves 2.x.

For code that stays on the FastMCP-level API surface (constructor, @mcp.tool(), run()), this has been sufficient: both lines pass the same test suite unchanged.

Proposal

A short section, roughly "Supporting 1.x and 2.x during the transition", covering:

1. the import shim above,
2. dependency-pin guidance (mcp>=1.2.0,<3, and why an upper bound of <2 alone strands your users),
3. testing both lines in CI (one extra pinned job is enough), and
4. a sentence on when to drop the 1.x path.

I would keep it to roughly 40 to 60 lines.

Scoping questions before I write anything

• Trim the migration guide to genuine v1-to-v2 breaking changes #3183 is trimming migration.md down to genuine breaking changes, so this may not belong there. Would you rather see it as a short section in migration.md, or as a separate small docs page (e.g. docs/compatibility.md)?
• If the answer is "we deliberately do not want to encourage dual-major support", that is a fair position; happy to close.

If maintainers think it is worth having, I will send the PR.