Point imports of mcp.server.fastmcp at the migration guide
v1 code running against mcp 2 fails with a bare ModuleNotFoundError: No module named 'mcp.server.fastmcp', which reads like a broken install. This adds a 16-line src/mcp/server/fastmcp.py whose only statement raises the same exception with a message that says what happened:
ModuleNotFoundError: No module named 'mcp.server.fastmcp'. This is mcp 2.x, where FastMCP was renamed to MCPServer (from mcp.server.mcpserver import MCPServer) and other APIs changed; see the migration guide at https://py.sdk.modelcontextprotocol.io/v2/migration/#fastmcp-renamed-to-mcpserver or pin 'mcp<2' to keep running v1 code.
Not #3189: nothing is aliased or re-exported and no warning is emitted. The old path still fails to import; it just says why.
Motivation and Context
Since 2.0 shipped the bare string has been quoted in roughly a thousand downstream GitHub issues and PRs (one here, #3309), and new v1-shaped code keeps being written. It raises ModuleNotFoundError with name= set, rather than ImportError, because dual-version shims in the wild catch that class specifically or check exc.name; those keep working unchanged. It's a module file rather than a package so one file covers every mcp.server.fastmcp.* path, and it's excluded from the API reference so it stays undocumented and deletable in any release.
How Has This Been Tested?
New tests/server/test_fastmcp.py (message snapshot, .name, nothing left in sys.modules, deep submodule path, v1-first fallback idiom); ./scripts/test, pyright, docs build; and by hand via python -c, mcp run, and a built wheel.
Breaking Changes
None. Exception type and .name are unchanged; only the message text differs, and importlib.util.find_spec("mcp.server.fastmcp") now returns a spec instead of None.
Types of changes
- Bug fix (non-breaking change which fixes an issue)
- New feature (non-breaking change which adds functionality)
- Breaking change (fix or feature that would cause existing functionality to change)
- Documentation update
Checklist
- I am assigned to the linked issue (or it is labeled
help wanted, or I'm a maintainer) - I have disclosed any AI assistance and can explain the change in my own words
- I have read the MCP Documentation
- My code follows the repository's style guidelines
- New and existing tests pass locally
- I have added appropriate error handling
- I have added or updated documentation as needed
Additional context
Deliberately out of scope: the other removed v1 module paths (near-zero reports), from mcp.server import FastMCP and McpError (would need per-symbol __getattr__, cf. c27f95c8).