fastmcp-server

# FastMCP 3.0 Server Development

Complete reference for building production-ready MCP (Model Context Protocol) servers with FastMCP 3.0 - the fast, Pythonic framework for connecting LLMs to tools and data.

## When to use this skill

**Use FastMCP Server when:**
- Creating a new MCP server in Python
- Adding tools, resources, or prompts to an MCP server
- Implementing authentication (OAuth, OIDC, token verification)
- Setting up middleware for logging, rate limiting, or authorization
- Configuring providers (local, filesystem, skills, custom)
- Building production MCP servers with telemetry and storage
- Upgrading from FastMCP 2.x to 3.0

**Key areas covered:**
- **Tools & Resources** (CORE): Decorators, validation, return types, templates
- **Context & DI** (CORE): MCP context, dependency injection, background tasks
- **Authentication** (SECURITY): OAuth, OIDC, token verification, proxy patterns
- **Authorization** (SECURITY): Scope-based and role-based access control
- **Middleware** (ADVANCED): Request/response pipeline, built-in middleware
- **Providers** (ADVANCED): Local, filesystem, skills, and custom providers
- **Features** (ADVANCED): Pagination, sampling, storage, OpenTelemetry, versioning

## Quick reference

### Core patterns

**Create a server with tools:**
```python
from fastmcp import FastMCP

mcp = FastMCP("MyServer")

@mcp.tool
def add(a: int, b: int) -> int:
    """Add two numbers"""
    return a + b
```

**Create a resource:**
```python
@mcp.resource("data://config")
def get_config() -> dict:
    """Return server configuration"""
    return {"version": "1.0", "debug": False}
```

**Create a resource template:**
```python
@mcp.resource("users://{user_id}/profile")
def get_user_profile(user_id: str) -> dict:
    """Get a user's profile by ID"""
    return fetch_user(user_id)
```

**Create a prompt:**
```python
@mcp.prompt
def review_code(code: str, language: str = "python") -> str:
    """Review code for best practices"""
    return f"Review this {language} code:\n\n{code}"
```

**Run the server:**
```python
if __name__ == "__main__":
    mcp.run()

# Or with transport options:
# mcp.run(transport="sse", host="0.0.0.0", port=8000)
```

### Using context in tools

```python
from fastmcp import FastMCP, Context

mcp = FastMCP("MyServer")

@mcp.tool
def process_data(uri: str, ctx: Context) -> str:
    """Process data with logging and progress"""
    ctx.info(f"Processing {uri}")
    ctx.report_progress(0, 100)
    data = ctx.read_resource(uri)
    ctx.report_progress(100, 100)
    return f"Processed: {data}"
```

### Authentication setup

```python
from fastmcp import FastMCP
from fastmcp.server.auth import BearerAuthProvider

auth = BearerAuthProvider(
    jwks_uri="https://your-provider/.well-known/jwks.json",
    audience="your-api",
    issuer="https://your-provider/"
)

mcp = FastMCP("SecureServer", auth=auth)
```

## Key concepts

### Tools
Functions exposed as executable capabilities for LLMs. Decorated with `@mcp.tool`. Support Pydantic validation, async, custom return types, and annotations (readOnlyHint, destructiveHint).

### Resources & Templates
Static or dynamic data sources identified by URIs. Resources use fixed URIs (`data://config`), templates use parameterized URIs (`users://{id}/profile`). Support MIME types, annotations, and wildcard parameters.

### Context
The `Context` object provides access to MCP features within tools/resources: logging, progress reporting, resource access, LLM sampling, user elicitation, and session state.

### Dependency Injection
Inject values into tool/resource functions using `Depends()`. Supports HTTP requests, access tokens, custom dependencies, and generator-based cleanup patterns.

### Providers
Control where components come from. `LocalProvider` (default, decorator-based), `FileSystemProvider` (load from Python files on disk), `SkillsProvider` (packaged bundles), or custom providers.

### Authentication & Authorization
Multiple auth patterns: token verification (JWT, JWKS), OAuth proxy, OIDC proxy, remote OAuth, and full OAuth server. Authorization via scopes on components and middleware.

### Middleware
Intercept and modify requests/responses. Built-in middleware for rate limiting, error handling, logging, and response size limits. Custom middleware via `@mcp.middleware`.

## Using the references

Detailed documentation is organized in the `references/` folder:

### Getting Started
- **getting-started/installation.md** - Install FastMCP, optional dependencies, verify setup
- **getting-started/upgrade-guide.md** - Migrate from FastMCP 2.x to 3.0
- **getting-started/quickstart.md** - First server, tools, resources, prompts, running

### Server
- **server/server-class.md** - FastMCP server configuration, transport options, tag filtering
- **server/tools.md** - Tool decorator, parameters, validation, return types, annotations
- **server/resources-and-templates.md** - Resources, templates, URIs, wildcards, MIME types

### Context
- **context/mcp-context.md** - Context object, logging, progress, resource access, sampling
- **context/background-tasks.md** - Long-running operations with task support
- **context/dependency-injection.md** - Depends(), custom deps, HTTP request, access tokens
- **context/user-elicitation.md** - Request structured input from users during execution

### Features
- **features/icons.md** - Custom icons for tools, resources, prompts, and servers
- **features/lifespans.md** - Server lifecycle management and startup/shutdown hooks
- **features/client-logging.md** - Send log messages to MCP clients
- **features/middleware.md** - Request/response pipeline, built-in and custom middleware
- **features/pagination.md** - Paginate large component lists
- **features/progress-reporting.md** - Report progress for long-running operations
- **features/sampling.md** - Request LLM completions from the client
- **features/storage-backends.md** - Memory, file, and Redis storage for caching and tokens
- **features/opentelemetry.md** - Distributed tracing and observability
- **features/versioning.md** - Version components and filter by version ranges

### Authentication
- **authentication/token-verification.md** - JWT, JWKS, introspection, static keys, custom
- **authentication/remote-oauth.md** - Delegate auth to upstream OAuth provider
- **authentication/oauth-proxy.md** - Full OAuth proxy with PKCE, client management
- **authentication/oidc-proxy.md** - OpenID Connect proxy with auto-discovery
- **authentication/full-oauth-server.md** - Complete built-in OAuth server

### Authorization
- **authorization.md** - Scope-based access control, middleware authorization, patterns

### Providers
- **providers/local.md** - Default provider, decorator-based component registration
- **providers/filesystem.md** - Load components from Python files on disk
- **providers/skills.md** - Package and distribute component bundles
- **providers/custom.md** - Build custom providers for any component source

## Version history

**v1.0.0** (February 2026)
- Initial release covering FastMCP 3.0 (release candidate)
- 30 reference files across 7 categories
- Complete coverage of tools, resources, context, auth, providers, and features