Import fails after MCP Python SDK 2.0

If you need the server starting again and are not ready to change code

1. 1 Add the upper bound to the requirement itself, not just to the lockfile. The SDK's migration guide states the rule plainly: "If your package depends on mcp, keep a <2 upper bound until you've migrated." The v2.0.0 release notes give mcp>=1.28,<2 as the worked example.
2. 2 Re-resolve afterwards, because the bound alone does not move an environment that already installed 2.x. Run uv lock and then uv sync, or pip install -e . for a pip project. Confirm you landed on 1.x rather than assuming it.
3. 3 Find the requirement that actually pulled mcp in before you edit anything. uv tree --invert names it, and when the unbounded requirement belongs to a dependency rather than to you, editing your own pyproject.toml changes nothing — pin it in that project, or constrain it from yours.
4. 4 Treat the pin as temporary. The 1.x branch receives security fixes and critical bug fixes only, so the migration is still ahead of you; the pin buys the time to schedule it rather than removing the work.
5. 5 For a launcher you do not control the manifest of, bound it at the launch command. Adding "--with", "mcp<2" to a uvx server's arguments is the documented shape of this workaround, and it can be dropped once the package itself declares the bound. For a pipx install, pipx runpip <venv> install 'mcp<2' does the same to an existing environment.

# pyproject.toml — the bound the SDK's migration guide recommends.
dependencies = [
    "mcp>=1.28,<2",
]

If you would rather move to the 2.x line than carry a pin

1. 1 Change the import and the class name. FastMCP is now MCPServer, and the migration guide states that "All submodules under mcp.server.fastmcp.* are now under mcp.server.mcpserver.* with the same structure" — so a submodule import is the same rewrite one level deeper.
2. 2 Leave your handlers alone. Under what is unchanged on MCPServer, the guide is explicit: "@mcp.tool(), @mcp.resource(), @mcp.prompt(), and @mcp.completion() take the same arguments and handler signatures as v1." For most servers the whole diff is the import line and the constructor.
3. 3 Set the floor to 2 and keep an upper bound — mcp>=2,<3 — so the next major cannot do this to you again.
4. 4 Expect to serve older clients without configuring anything. The v2.0.0 release notes say v2 "still serves every 2025-era client from the same MCPServer, over Streamable HTTP and stdio, with nothing to configure", so migrating the server does not require your callers to move first.
5. 5 Read the known gaps before you commit to a date. The release notes exclude the tasks extension (SEP-2663) from 2.0.0, and on the client leave out DPoP proof binding (SEP-1932) and the workload-identity jwt-bearer grant. If you depend on one of those, the pin is the better answer this month.

# mcp 2.x. The import root and the class name change; the decorators do not.
from mcp.server.mcpserver import MCPServer

mcp = MCPServer("Demo")


@mcp.tool()
def add(a: int, b: int) -> int:
    return a + b

If your imports read from fastmcp import FastMCP rather than naming mcp

1. 1 Check which FastMCP you have, because there are two and only one is affected. The class this error is about lived at mcp.server.fastmcp inside the mcp package. The separately published fastmcp distribution has its own import root, and a from fastmcp import FastMCP line cannot raise this error.
2. 2 Expect fastmcp 3.x not to drag mcp 2.x in either. On PyPI today, fastmcp 3.4.5 requires fastmcp-slim[client,server]==3.4.5, whose client and server extras both declare mcp<2.0,>=1.24.0 — already bounded, so a fresh resolve of that line cannot reach 2.x.
3. 3 Look elsewhere in the tree if you see this error in a project that also uses fastmcp. Something else is requiring mcp without a bound; uv tree --invert names it.
4. 4 Know which line is built on SDK v2 before you upgrade to reach it. The fastmcp 4.0.0b1 release, published 2026-07-28, requires mcp>=2.0.0,<3.0.0 and mcp-types>=2.0.0,<3.0.0, and its notes state that MCP Python SDK v2 "rewrote the protocol layer end to end". It is a beta, so treat it as one.

Something else

This failure has one cause and two exits. An unbounded mcp requirement resolved to 2.x under code written for 1.x, so either bound the requirement below 2 and re-resolve, or move the import to mcp.server.mcpserver and the class to MCPServer. Establish which requirement pulled mcp in first: when it belongs to a dependency rather than to your project, the pin has to go where that requirement is declared, or be applied as a constraint from yours. Check the version before you debug anything else in the launch path — the process dies at import, so a token, a wrapper script, or a transport setting cannot be the cause no matter how recently you touched it.