Launch offer: use code LAUNCH20 for 20% off any single pack. See the packs

No module named 'mcp.server.fastmcp'? Fix It for MCP SDK v2

Published 2026-11-12 · 4 min read · by AgentKit Co

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

  1. Run pip show mcp and check the version.
  2. On 2.x, change the import to from mcp.server.mcpserver import MCPServer.
  3. Rename camelCase attribute access to snake_case.
  4. Move host / port / transport options to mcp.run().
  5. Or pin mcp<2 until you have time to test.
  6. Tell your agent about v2 in AGENTS.md so 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.

Keep reading

Agent Skills (SKILL.md) Explained: Formats, Folders and SafetyWhat an Agent Skill is, how SKILL.md works, which folders Claude Code, Codex, Cursor and Copilot read, and how to write and vet one. Checked on 2026-10-17.4 min readAGENTS.md Examples: 7 Copy-Paste Files for Real Projects (2026)Seven AGENTS.md examples to copy: Next.js, Python API, Go, a monorepo with nested files, a global ~/.codex file, an override and review rules.7 min readWhat Is an AI Agent? Plain-English Guide for BeginnersWhat an AI agent is, how it differs from a chatbot or automation, and the four building blocks every agent has. No jargon.4 min read