No module named 'mcp.server.fastmcp'? Fix It for MCP SDK v2
If a Python MCP server that worked last month now dies on start-up with this:
ModuleNotFoundError: No module named 'mcp.server.fastmcp'
nothing is wrong with your code. pip installed version 2 of the official MCP Python SDK, and in v2 the FastMCP class was renamed to MCPServer. Claude Code, Cursor or any other client then shows the server as failed, because the process exits before it can answer.
We hit this ourselves on 2026-11-12 with mcp 2.3.0 and checked every fix below against that version and the official v1 → v2 migration guide. The SDK is moving fast, so re-check the guide for anything you rely on.
The two-line fix
# Before (mcp 1.x)
from mcp.server.fastmcp import FastMCP
mcp = FastMCP("notes")
# After (mcp 2.x)
from mcp.server.mcpserver import MCPServer
mcp = MCPServer("notes")
Your @mcp.tool(), @mcp.resource() and @mcp.prompt() decorators keep working as they were. Every submodule moved the same way: mcp.server.fastmcp.* is now mcp.server.mcpserver.*.
Not ready to migrate? Pin v1
The error message itself suggests this, and the migration guide says the 1.x line still gets critical fixes. In requirements.txt or pyproject.toml:
mcp<2
Pinning is fine as a stopgap. Do it if you share the server with a team and can't test the upgrade today.
A complete v2 server you can copy
This is the exact file we ran. It gives an agent two tools over a folder of markdown notes, and it refuses to read anything outside that folder.
from pathlib import Path
from mcp.server.mcpserver import MCPServer
mcp = MCPServer("notes")
NOTES = Path(__file__).parent / "notes"
@mcp.tool()
def search_notes(query: str) -> list[str]:
"""Return the names of markdown notes that contain the query (case-insensitive)."""
q = query.lower()
return sorted(p.name for p in NOTES.glob("*.md") if q in p.read_text().lower())
@mcp.tool()
def read_note(name: str) -> str:
"""Return the full text of one note from the notes folder."""
path = (NOTES / name).resolve()
if path.parent != NOTES.resolve() or path.suffix != ".md":
raise ValueError("Only .md files inside the notes folder can be read")
return path.read_text()
if __name__ == "__main__":
mcp.run() # stdio transport by default
Register it with Claude Code (adjust the paths):
claude mcp add notes -- /path/to/venv/bin/python /path/to/server.py
Then run /mcp in Claude Code to check it shows as connected. Pointing at the virtualenv's own python matters: if Claude Code starts the server with a different interpreter, you get import errors that look like this one but aren't. Our .mcp.json examples cover project-scoped config and env vars.
The other v2 changes most people hit next
From the migration guide's "changes almost every project hits" list, these are the ones a small server or test script runs into first:
| Symptom | Cause | Fix |
|---|---|---|
AttributeError: ... has no attribute 'isError' (or inputSchema, nextCursor) |
Fields are snake_case in Python now | result.is_error, tool.input_schema, next_cursor |
TypeError: MCPServer.__init__() got an unexpected keyword argument 'port' |
Transport settings moved off the constructor | mcp.run(transport="streamable-http", host=..., port=...) |
ImportError: cannot import name 'McpError' |
Renamed | from mcp import MCPError |
ModuleNotFoundError: No module named 'httpx' in your own code |
The SDK switched to httpx2 and no longer installs httpx |
Add httpx to your own dependencies |
instructions silently stop reaching the client |
New positional parameters (title, description) in the constructor |
Pass instructions= by keyword |
mcp.get_context() fails |
Removed | Add a ctx: Context parameter to the tool |
The snake_case one caught our own test client: result.isError raised AttributeError until we changed it to result.is_error. Note that the wire format is still camelCase, so only your Python attribute access changes.
Make your agent stop writing v1 code
Coding agents learned MCP from v1 examples, so they will keep writing from mcp.server.fastmcp import FastMCP unless you tell them otherwise. Add a line to your AGENTS.md or CLAUDE.md:
## MCP servers
- We use the MCP Python SDK v2 (`mcp>=2,<3`). Import `MCPServer` from
`mcp.server.mcpserver`. Never use `mcp.server.fastmcp` or `FastMCP`.
- Python attribute names on MCP types are snake_case (`is_error`, `input_schema`).
That is the kind of rule our AI Coding Agent Config Kit is built around: short, specific instructions that stop an agent repeating the same mistake. If your instructions file is being ignored, see AGENTS.md not working.
Quick checklist
- Run
pip show mcpand check the version. - On 2.x, change the import to
from mcp.server.mcpserver import MCPServer. - Rename camelCase attribute access to snake_case.
- Move
host/port/ transport options tomcp.run(). - Or pin
mcp<2until you have time to test. - Tell your agent about v2 in
AGENTS.mdso it stops regressing.
AI Coding Agent Config Kit
Instruction-file templates for 12 stacks and 12 prompts that write and audit them. 34-page PDF, $14.
Not ready to buy? Start with the free PDF.
Get 10 of our most-used prompts as a free PDF from Gumroad. You will be asked for your email so Gumroad can deliver it.