Skip to main content
This guide covers breaking changes and migration steps when upgrading FastMCP.

​
v3.0.0

Most servers need only one change: update your import from from mcp.server.fastmcp import FastMCP to from fastmcp import FastMCP. The sections below cover less common breaking changes.

​
Breaking Changes

​
WSTransport Removed

Use StreamableHttpTransport instead.

​
Auth Provider Environment Variables Removed

Auth providers no longer auto-load configuration. Read them explicitly: 
import os

auth = GitHubProvider(
    client_id=os.environ["GITHUB_CLIENT_ID"],
    client_secret=os.environ["GITHUB_CLIENT_SECRET"],
)

​
Component enable()/disable() Moved to Server

These methods moved from component objects to the server: 
# Before
tool = await server.get_tool("my_tool")
tool.disable()

# After
server.disable(names={"my_tool"}, components=["tool"])

​
Listing Methods Return Lists

get_tools(), get_resources(), get_prompts(), and get_resource_templates() now return lists instead of dicts: 
# Before
tools = await server.get_tools()
tool = tools["my_tool"]

# After
tools = await server.get_tools()
tool = next((t for t in tools if t.name == "my_tool"), None)

​
Prompts Use Message Class

Use Message instead of mcp.types.PromptMessage: 
# Before
from mcp.types import PromptMessage, TextContent

@mcp.prompt
def my_prompt() -> PromptMessage:
    return PromptMessage(role="user", content=TextContent(type="text", text="Hello"))

# After
from fastmcp.prompts import Message

@mcp.prompt
def my_prompt() -> Message:
    return Message("Hello")

​
Context State Methods Are Async

ctx.set_state() and ctx.get_state() are now async. State persists across the session: 
# Before
ctx.set_state("key", "value")
value = ctx.get_state("key")

# After
await ctx.set_state("key", "value")
value = await ctx.get_state("key")

​
Server Banner Environment Variable Renamed

FASTMCP_SHOW_CLI_BANNER is now FASTMCP_SHOW_SERVER_BANNER.

​
OpenAPI timeout Parameter Removed

Configure timeout on the httpx client directly. The client parameter is now optional — when omitted, a default client is created from the spec’s servers URL with a 30-second timeout. 
# Before
provider = OpenAPIProvider(spec, client, timeout=60)

# After
client = httpx.AsyncClient(base_url="https://api.example.com", timeout=60)
provider = OpenAPIProvider(spec, client)

​
Metadata Namespace Renamed

The FastMCP metadata namespace changed from _fastmcp to fastmcp, and metadata is now always included. The include_fastmcp_meta parameter has been removed from FastMCP() and to_mcp_tool()—remove any usage of this parameter. 
# Before
tags = tool.meta.get("_fastmcp", {}).get("tags", [])

# After
tags = tool.meta.get("fastmcp", {}).get("tags", [])

​
Behavior Changes

​
Decorators Return Functions

Decorators now return your original function instead of a component object. This means functions stay callable for testing: 
@mcp.tool
def greet(name: str) -> str:
    return f"Hello, {name}!"

greet("World")  # Works! Returns "Hello, World!"
If you relied on the old behavior (treating greet as a FunctionTool), set FASTMCP_DECORATOR_MODE=object for v2 compatibility.

​
Deprecated Features

These still work but emit warnings. Update when convenient.

​
mount() prefix → namespace

# Deprecated
main.mount(subserver, prefix="api")

# New
main.mount(subserver, namespace="api")

​
include_tags/exclude_tags → enable()/disable()

# Deprecated
mcp = FastMCP("server", exclude_tags={"internal"})

# New
mcp = FastMCP("server")
mcp.disable(tags={"internal"})

​
tool_serializer → ToolResult

Return ToolResult from your tools for explicit serialization control instead of using the tool_serializer parameter.

​
add_tool_transformation() → add_transform()

# Deprecated
mcp.add_tool_transformation("name", config)

# New
from fastmcp.server.transforms import ToolTransform
mcp.add_transform(ToolTransform({"name": config}))

​
FastMCP.as_proxy() → create_proxy()

# Deprecated
proxy = FastMCP.as_proxy("http://example.com/mcp")

# New
from fastmcp.server import create_proxy
proxy = create_proxy("http://example.com/mcp")

​
v2.14.0

​
OpenAPI Parser Promotion

The experimental OpenAPI parser is now standard. Update imports: 
# Before
from fastmcp.experimental.server.openapi import FastMCPOpenAPI

# After
from fastmcp.server.openapi import FastMCPOpenAPI

​
Removed Deprecated Features

  • BearerAuthProvider → use JWTVerifier
  • Context.get_http_request() → use get_http_request() from dependencies
  • from fastmcp import Image → use from fastmcp.utilities.types import Image
  • FastMCP(dependencies=[...]) → use fastmcp.json configuration
  • FastMCPProxy(client=...) → use client_factory=lambda: ...
  • output_schema=False → use output_schema=None

​
v2.13.0

​
OAuth Token Key Management

The OAuth proxy now issues its own JWT tokens. For production, provide explicit keys: 
auth = GitHubProvider(
    client_id=os.environ["GITHUB_CLIENT_ID"],
    client_secret=os.environ["GITHUB_CLIENT_SECRET"],
    base_url="https://your-server.com",
    jwt_signing_key=os.environ["JWT_SIGNING_KEY"],
    client_storage=RedisStore(host="redis.example.com"),
)
See OAuth Token Security for details.