Upgrade or Convert to FastMCP 3.x

Two migration paths covered here: Python 2.x→3.x and JS/TS→Python. Read references/breaking-changes.md for the complete 17-item checklist. Read references/js-conversion.md for JavaScript/TypeScript conversion patterns.

Python 2.x → 3.x: Quick Start

The three changes you'll hit immediately:

# 1. Import changed
from fastmcp import FastMCP          # NOT: from mcp.server.fastmcp import FastMCP

# 2. State is async now
await ctx.set_state("key", "value")  # NOT: ctx.set_state(...)
value = await ctx.get_state("key")   # NOT: ctx.get_state(...)

# 3. Listing returns lists, not dicts
tools = await server.list_tools()    # NOT: server.get_tools()

Then update dependencies:

uv add "fastmcp>=3.1.0"

For current guidance, treat latest 3.x as baseline (fastmcp>=3.1.0 today). CodeMode support starts in 3.1 and remains experimental.

JS/TS → Python: Quick Start

The core mapping is simple — JS has monolithic handlers, Python has one function per tool with type annotations replacing zod schemas:

// JS: One giant handler
server.setRequestHandler(CallToolRequestSchema, async (request) => {
  if (request.params.name === "get_weather") { ... }
});

# Python: One decorated function per tool
@mcp.tool
def get_weather(city: str, units: Literal["celsius", "fahrenheit"] = "celsius") -> dict:
    """Get weather for a city."""
    return fetch_weather(city, units)

Read references/js-conversion.md for the full dependency mapping table and pattern-by-pattern conversion guide.

After Migration

1. Run uv run python -W all server.py to surface deprecation warnings
2. Test all tools with the in-memory client — see mcp-testing skill
3. Adopt new 3.x features: tool timeouts, versioning, fastmcp.json, CurrentContext()
4. For large tool catalogs, evaluate mcp-code-mode (3.1+, experimental) for staged discovery and server-side composition.