docs: no guidance for supporting SDK 1.x and 2.x at the same time

[haiiibin]

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.

[MilkyWay008]

Your shim + pin setup is basically the standard dual-support pattern and it's solid — the CI job force-installing 1.x is a nice touch. One gap to keep in mind: it only covers the FastMCP-level surface, so anything else that moved between majors (client config, streamable http, low-level server bits) still breaks fresh installs on 2.0.0. For placement I'd go a separate compat page linked from migration.md rather than stuffing it into a doc that keeps getting trimmed — a one-way migration guide plus a running compat note reads cleaner.

[haiiibin]

Thanks, that matches my read. A separate compat page linked from migration.md keeps the migration guide one-way and trimmed, so I would scope it that way: a short docs/compatibility.md with the shim, the pin guidance, and the CI job.

Good point on surface coverage. The shim only protects FastMCP-level code, so the page should say that plainly and list the other import moves (client config, streamable HTTP, low-level server) with pointers to their migration entries rather than pretending one shim covers everything.

I will hold off on the PR until a maintainer weighs in on whether they want the page at all.