mcp 2.x · python sdk
ImportError: cannot import name 'McpError' from 'mcp.shared.exceptions'
mcp 2.0 renamed the exception class McpError to MCPError. A package that was written for mcp 1.x and asks for mcp with no upper bound gets mcp 2.x from a plain install and stops at start-up.
The same cause gives: ImportError: cannot import name 'McpError' from 'mcp'.
You only want to start the server
Install the package with the Python SDK below 2. With uv:
uvx --with "mcp<2" <package>
With pip, in the environment of the server:
pip install "mcp<2"
In an MCP client config, put --with and mcp<2 in front of the package name in the args of uvx. The SDK keeps the 1.x line supplied with critical fixes.
You publish the server
You have two fixes. The fast one is an upper bound in the dependencies of the package, then a new release:
dependencies = ["mcp>=1.2,<2"]
The SDK's migration guide says the same: keep a <2 upper bound until you have moved your code. The full fix is the move to mcp 2.x. Before:
from mcp.shared.exceptions import McpError raise McpError(ErrorData(code=INVALID_REQUEST, message="bad input"))
After:
from mcp.shared.exceptions import MCPError raise MCPError(INVALID_REQUEST, "bad input")
- from mcp import MCPError works too.
- Read the text of a caught error from e.message. In mcp 1.x it was e.error.message.
Source: the section of the migration guide of the MCP Python SDK. mcp 2.0.0 came to PyPI on 28 July 2026. The examples are the guide's own.
Servers with this error 2026-11-14
3 PyPI package servers in the official MCP registry stopped with this error in the newest daily probe. The probe installs each package in a container as a client does, with no version pins, and starts it.
- AWS MCP Server mcp-proxy-for-aws
- Grafyx grafyx-mcp
- io.github.lchinglen/time-mcp-server lchinglen-time-mcp-server
Is your server in the list after a fix? Its page updates with the next weekly check of the package. How the probe works.
Other errors of mcp 2.x
- ModuleNotFoundError: No module named 'mcp.server.fastmcp'
- AttributeError: 'Server' object has no attribute 'list_tools'
- ImportError: cannot import name 'FastMCP' from 'mcp.server'
- ImportError: cannot import name 'streamablehttp_client' from 'mcp.client.streamable_http'
All of them, with counts. The full list of changes is in the migration guide.