mcp 2.0.0 breaks imports: FastMCP renamed to MCPServer, module moved

[nirvana6]

Problem

jupyter-mcp-server (installed from git+https://github.com/datalayer/jupyter-mcp-server.git) crashes at import time with mcp >= 2.0.0:

ModuleNotFoundError: No module named 'mcp.server.fastmcp'

This happens in jupyter_mcp_server/tools/jupyter_cite_prompt.py, line 11:

from mcp.server.fastmcp.prompts.base import UserMessage

Root Cause

The mcp package (modelcontextprotocol/python-sdk) released v2.0.0, which renamed FastMCP to MCPServer and moved the entire module:

• v1: from mcp.server.fastmcp import FastMCP
• v2: from mcp.server.mcpserver import MCPServer

Full migration guide: https://github.com/modelcontextprotocol/python-sdk/blob/main/docs/migration.md#fastmcp-renamed-to-mcpserver

The related GitHub issue tracking the rename: modelcontextprotocol/python-sdk#1732

Why this breaks now

The pyproject.toml declares:

"mcp[cli]>=1.10.1"

This has no upper bound, so uv / pip resolves to mcp==2.0.0 (released 2026-07-28). The previous mcp==1.29.0 worked fine.

Current workaround

Users can pin manually:

--with "mcp[cli]>=1.10.1,<2.0.0"

Suggested fix

Either:

1. (Quick) Add <2.0.0 to the dependency: "mcp[cli]>=1.10.1,<2.0.0"
2. (Long-term) Migrate imports to the v2 API and bump to "mcp[cli]>=2.0.0"

[echarles]

(Long-term) Migrate imports to the v2 API and bump to "mcp[cli]>=2.0.0"

Would prefer that one to avoid double work.

[ebarkhordar]

Two import sites break at HEAD (c69b8ab), not one. The second is jupyter_mcp_server/server.py:15, from mcp.server import FastMCP, which does not contain the string mcp.server.fastmcp and so does not turn up in a search for the moved module.

Renaming just those two imports (mcp.server.mcpserver.prompts.base for UserMessage, MCPServer for FastMCP) moves the failure to the constructor:

File "/src/jupyter_mcp_server/server.py", line 189, in <module>
    mcp = FastMCPWithCORS(name="Jupyter MCP Server", json_response=False, stateless_http=True)
TypeError: MCPServer.__init__() got an unexpected keyword argument 'json_response'

json_response and stateless_http moved from the constructor to streamable_http_app():

• 1.29.0: FastMCP.__init__(..., json_response, stateless_http), streamable_http_app(self)
• 2.0.0: MCPServer.__init__ accepts neither, streamable_http_app(self, *, json_response=False, stateless_http=False, ...)

That interacts badly with the CORS subclass. FastMCPWithCORS.streamable_http_app() (server.py:152) takes no arguments and calls super().streamable_http_app(), and utils.py:344 passes the bound method to uvicorn.run as an ASGI factory, so once the two kwargs leave the constructor there is no call site left that can supply them. Dropping them to clear the TypeError imports and serves fine, with stateless_http quietly falling back to the 2.0.0 default:

streamable_http_app()                    -> _session_manager.stateless = False
streamable_http_app(stateless_http=True) -> _session_manager.stateless = True

So the override needs to pass them itself rather than inherit the defaults.

The rest of the surface is unchanged, which keeps the migration small: every other mcp import in the tree still resolves under 2.0.0 (mcp.types.ImageContent and ToolAnnotations across 10 modules, mcp.server.auth.provider.AccessToken, mcp.server.auth.middleware.bearer_auth.BearerAuthBackend, and mcp.ClientSession plus mcp.client.streamable_http.streamable_http_client in tests/test_common.py), as does every attribute used on the server object: .tool, .prompt, .custom_route, .list_tools, .call_tool, .run, .streamable_http_app, ._token_verifier.

One note on ordering: open PR #309 adds from mcp.server.fastmcp import Context to server.py, so whichever of the two lands second will need that line as mcp.server.mcpserver too (Context is exported from there, and is not re-exported from mcp.server).

Checked in a clean python:3.12-slim container against HEAD c69b8ab with mcp[cli]==2.0.0, and against 1.29.0 for the comparison. I did not run the test suite under 2.0.0, so this covers import and construction only, not behaviour past startup.

Happy to send the migration PR if it is not already in hand.

[echarles]

Happy to send the migration PR if it is not already in hand.

Sounds like a plan :)

[echarles]

fyi I have opened #328 as a quick fix to set mcp < 2 - bumping to 2 is pulling upstream deps on consumer projects...

[echarles]

merged, with pin mcp<2 in main for now.