GeezerVison

The World Wide Web, restored to 800 pixels of glory.

GeezerVison is showing github.com — Point imports of mcp.server.fastmcp at the migration guide by maxisbey · Pull Request #3388 · modelcontextprotocol/python-sdk

Conversation

maxisbey commented Aug 25, 2026 •

edited

Loading

Uh oh!

There was an error while loading. Please reload this page.

Copy link

Copy Markdown

Contributor

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. c27f95c).

_{AI Disclaimer}

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

All reactions

maxisbey added 2 commits

August 25, 2026 08:45


          Point imports of mcp.server.fastmcp at the migration guide

b189452

v1 code running against mcp 2 fails with a bare "No module named
'mcp.server.fastmcp'", which reads like a broken install and gives no
hint that the package was renamed in a new major version. Add a plain
module at the old path whose only statement raises ModuleNotFoundError
with a message that keeps the canonical prefix, names the replacement
import, links the migration guide, and mentions pinning mcp<2.

The exception type and its `name` attribute match what a genuinely
missing module produces, so existing `except ImportError`,
`except ModuleNotFoundError`, and `exc.name` fallbacks keep working and
nothing is re-exported or warned about. The module is a file rather
than a package so tools that walk packages do not execute it, and it is
excluded from the generated API reference since it carries no API.


          Describe the old import path's pointer in the migration guide

The first-symptom row keeps the verbatim 2.0/2.1 text people search
for while staying true once the message carries a pointer, and the
FastMCP section notes that the old path raises ModuleNotFoundError and
that dual-version import fallbacks continue to work.

maxisbey marked this pull request as ready for review

August 25, 2026 15:37

github-actions Bot commented Aug 25, 2026

Copy link

Copy Markdown

Contributor

📚 Documentation preview


Preview	https://pr-3388.mcp-python-docs.pages.dev
Deployment	https://ddc25858.mcp-python-docs.pages.dev
Commit	`3330346`
Triggered by	@maxisbey
Updated	2026-08-25 15:38:03 UTC

All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

cubic-dev-ai Bot reviewed

Aug 25, 2026

View reviewed changes

cubic-dev-ai Bot left a comment

Copy link

Copy Markdown

There was a problem hiding this comment.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No issues found across 4 files

_{Re-trigger cubic}

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

All reactions

maxisbey merged commit 0921d94 into main

Aug 25, 2026

41 checks passed

Uh oh!

There was an error while loading. Please reload this page.

maxisbey deleted the fastmcp-import-tombstone branch

August 25, 2026 15:39

claude Bot reviewed

Aug 25, 2026

View reviewed changes

claude Bot left a comment

Copy link

Copy Markdown

Contributor

There was a problem hiding this comment.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Beyond the inline finding, I also checked that the new tombstone doesn't break v1-detection patterns: importlib.util.find_spec("mcp.server.fastmcp") now returns a spec instead of None, but any code that follows that check with an actual import still hits the pointer message, and the dominant try/except-ImportError dual-major guard is unaffected (ModuleNotFoundError subclasses ImportError, and the new tests cover it). Also confirmed the module raising at import leaves no sys.modules residue, and the gen_ref_pages.py exclusion just keeps the tombstone out of the API docs.

Extended reasoning...

The change adds a tombstone module at the removed v1 path mcp/server/fastmcp.py that raises ModuleNotFoundError (with the correct name=) pointing at the migration guide, plus docs and doc-generation exclusions and thorough tests. The one inline finding (the equally common v1 spelling from mcp.server import FastMCP still gets the bare error) is a coverage-scope question worth a maintainer's eye, so I am not approving over it. Separately, I examined whether making mcp.server.fastmcp discoverable again (find_spec returns a spec, pkgutil lists it) could misfire spec-based v1 detection and ruled it out: such detection is unusual for this path, and any subsequent real import still raises the pointer, while the try/except import guard the change explicitly targets keeps working since ModuleNotFoundError subclasses ImportError and the module is never left cached after raising.

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

All reactions

Comment thread

src/mcp/server/fastmcp.py

		"or pin 'mcp<2' to keep running v1 code."
		)

		raise ModuleNotFoundError(_MESSAGE, name=__name__)

claude Bot Aug 25, 2026

Copy link

Copy Markdown

Contributor

There was a problem hiding this comment.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟣 Pre-existing: the migration-pointer tombstone covers only the mcp.server.fastmcp module path, but v1 also re-exported the class from the package itself (v1's mcp/server/__init__.py had from .fastmcp import FastMCP), so the equally common v1 spelling from mcp.server import FastMCP still fails with the bare ImportError: cannot import name 'FastMCP' from 'mcp.server' and never sees the new pointer this PR adds. A module-level __getattr__ in src/mcp/server/__init__.py raising the same guidance for FastMCP (mirroring the _MESSAGE in src/mcp/server/fastmcp.py) would close the gap; docs/migration.md line 675 and the line-20 symptom row also only describe the ModuleNotFoundError path.

Extended reasoning...

A v1 user whose server does from mcp.server import FastMCP (a valid, exported v1 import path) upgrades to a 2.x release containing this change. Instead of the improved message pointing at MCPServer and the migration guide, they still get the uninformative ImportError: cannot import name 'FastMCP' from 'mcp.server' — exactly the confusing experience this PR was written to eliminate — because the tombstone only intercepts imports of the mcp.server.fastmcp module, not the FastMCP attribute of mcp.server.

Verification: pre-existing — src/mcp/server/init.py defines no FastMCP and no module-level __getattr__ (its imports are only CacheHint, ServerRequestContext, NotificationOptions, Server, MCPServer, InitializationOptions), so from mcp.server import FastMCP — a valid v1 spelling, since v1's mcp/server/__init__.py re-exported FastMCP via from .fastmcp import FastMCP and listed it in __all__ — raise

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

claude[bot] reacted with thumbs up emoji

claude[bot] reacted with thumbs down emoji

All reactions

👍 1 reaction
👎 1 reaction

maxisbey mentioned this pull request

Aug 26, 2026

[v2.0.x] Point imports of mcp.server.fastmcp at the migration guide #3393

Merged

9 of 11 tasks

haiiibin mentioned this pull request

Sep 14, 2026

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

Closed

bitwize-music mentioned this pull request

Oct 13, 2026

chore(deps): bump pypdf (8 advisories), mcp, ruff, mypy and 5 others bitwize-music-studio/claude-ai-music-skills#577

Merged

Reviewers

cubic-dev-ai[bot]

cubic-dev-ai[bot] left review comments

claude[bot]

claude[bot] left review comments

Uh oh!

There was an error while loading. Please reload this page.

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Uh oh!

There was an error while loading. Please reload this page.

1 participant

Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.

You are visitor 01402503 — GeezerVison does not store the pages you look up.
Best viewed with Netscape Navigator 4.7 or Internet Explorer 6 at 800×600. No cookies required.

GeezerVison

Conversation

maxisbey commented Aug 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Motivation and Context

How Has This Been Tested?

Breaking Changes

Types of changes

Checklist

Additional context

Uh oh!

github-actions Bot commented Aug 25, 2026

📚 Documentation preview

Uh oh!

cubic-dev-ai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

claude Bot left a comment

Choose a reason for hiding this comment

Uh oh!

claude Bot Aug 25, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

maxisbey commented Aug 25, 2026 •

edited

Loading

Uh oh!

There was an error while loading. Please reload this page.