FastMCP - Build MCP Servers in Python

FastMCP is a Python framework for building Model Context Protocol (MCP) servers that expose tools, resources, and prompts to Large Language Models like Claude. This skill provides production-tested patterns, error prevention, and deployment strategies for building robust MCP servers.

Quick Start

Installation

pip install fastmcp
# or
uv pip install fastmcp

Minimal Server

from fastmcp import FastMCP

# MUST be at module level for FastMCP Cloud
mcp = FastMCP("My Server")

@mcp.tool()
async def hello(name: str) -> str:
    """Say hello to someone."""
    return f"Hello, {name}!"

if __name__ == "__main__":
    mcp.run()

Run it:

# Local development
python server.py

# With FastMCP CLI
fastmcp dev server.py

# HTTP mode
python server.py --transport http --port 8000

What's New in v2.14.x (December 2025)

v2.14.2 (December 31, 2024)

• MCP SDK pinned to <2.x for compatibility
• Supabase provider gains auth_route parameter
• Bug fixes: outputSchema $ref resolution, OAuth Proxy validation, OpenAPI 3.1 support

v2.14.1: Sampling with Tools (SEP-1577)

• ctx.sample() now accepts tools for agentic workflows
• AnthropicSamplingHandler promoted from experimental
• ctx.sample_step() for single LLM call returning SampleStep
• Python 3.13 support added

v2.14.0: Background Tasks (SEP-1686)

• Protocol-native background tasks for long-running operations
• Add task=True to async decorators; progress tracking without blocking
• MCP 2025-11-25 specification support
• SEP-1699: SSE polling and event resumability
• SEP-1330: Multi-select enum elicitation schemas
• SEP-1034: Default values for elicitation schemas

⚠️ Breaking Changes (v2.14.0):

• BearerAuthProvider module removed (use JWTVerifier or OAuthProxy)
• Context.get_http_request() method removed
• fastmcp.Image top-level import removed (use from fastmcp.utilities import Image)
• enable_docket, enable_tasks settings removed (always enabled)
• run_streamable_http_async(), sse_app(), streamable_http_app(), run_sse_async() methods removed
• dependencies parameter removed from decorators
• output_schema=False support eliminated
• FASTMCP_SERVER_ environment variable prefix deprecated

Known Compatibility:

• MCP SDK pinned to <2.x (v2.14.2+)

What's New in v3.0.0 (Beta - January 2026)

⚠️ MAJOR BREAKING CHANGES - FastMCP 3.0 is a complete architectural refactor.

Provider Architecture

All components now sourced via Providers:

• FileSystemProvider - Discover decorated functions from directories with hot-reload
• SkillsProvider - Expose agent skill files as MCP resources
• OpenAPIProvider - Auto-generate from OpenAPI specs
• ProxyProvider - Proxy to remote MCP servers

from fastmcp import FastMCP
from fastmcp.providers import FileSystemProvider

mcp = FastMCP("server")
mcp.add_provider(FileSystemProvider(path="./tools", reload=True))

Transforms (Component Middleware)

Modify components without changing source code:

• Namespace, rename, filter by version
• ResourcesAsTools - Expose resources as tools
• PromptsAsTools - Expose prompts as tools

from fastmcp.transforms import Namespace, VersionFilter

mcp.add_transform(Namespace(prefix="api"))
mcp.add_transform(VersionFilter(min_version="2.0"))

Component Versioning

@mcp.tool(version="2.0")
async def fetch_data(query: str) -> dict:
    # Clients see highest version by default
    # Can request specific version
    return {"data": [...]}

Session-Scoped State

@mcp.tool()
async def set_preference(key: str, value: str, ctx: Context) -> dict:
    await ctx.set_state(key, value)  # Persists across session
    return {"saved": True}

@mcp.tool()
async def get_preference(key: str, ctx: Context) -> dict:
    value = await ctx.get_state(key, default=None)
    return {"value": value}

Other Features

• --reload flag for auto-restart during development
• Automatic threadpool dispatch for sync functions
• Tool timeouts
• OpenTelemetry tracing
• Component authorization: @tool(auth=require_scopes("admin"))

Migration Guide

Pin to v2 if not ready:

# requirements.txt
fastmcp<3

For most servers, updating the import is all you need:

# v2.x and v3.0 compatible
from fastmcp import FastMCP

mcp = FastMCP("server")
# ... rest of code works the same

See: Official Migration Guide

---

Core Concepts

Tools

Functions LLMs can call. Best practices: Clear names, comprehensive docstrings (LLMs read these!), strong type hints (Pydantic validates), structured returns, error handling.

@mcp.tool()
async def async_tool(url: str) -> dict:  # Use async for I/O
    async with httpx.AsyncClient() as client:
        return (await client.get(url)).json()

Resources

Expose data to LLMs. URI schemes: data://, file://, resource://, info://, api://, or custom.

@mcp.resource("user://{user_id}/profile")  # Template with parameters
async def get_user(user_id: str) -> dict:  # CRITICAL: param names must match
    return await fetch_user_from_db(user_id)

Prompts

Pre-configured prompts with parameters.

@mcp.prompt("analyze")
def analyze_prompt(topic: str) -> str:
    return f"Analyze {topic} considering: state, challenges, opportunities, recommendations."

Context Features

Inject Context parameter (with type hint!) for advanced features:

Elicitation (User Input):

from fastmcp import Context

@mcp.tool()
async def confirm_action(action: str, context: Context) -> dict:
    confirmed = await context.request_elicitation(prompt=f"Confirm {action}?", response_type=str)
    return {"status": "completed" if confirmed.lower() == "yes" else "cancelled"}

Progress Tracking:

@mcp.tool()
async def batch_import(file_path: str, context: Context) -> dict:
    data = await read_file(file_path)
    for i, item in enumerate(data):
        await context.report_progress(i + 1, len(data), f"Importing {i + 1