davila7/claude-code-templates / cli-tool/components/skills/development/fastmcp-server
fastmcp-server
VerifiedComplete guide for building MCP servers with FastMCP 3.0 - tools, resources, authentication, providers, middleware, and deployment. Use when creating Python MCP servers or integrating AI models with external tools and data.
references/features/storage-backends.md
View on GitHub# Storage Backends
> Configure persistent and distributed storage for caching and OAuth state management
FastMCP uses pluggable storage backends for caching responses and managing OAuth state. By default, all storage is in-memory, which is perfect for development but doesn't persist across restarts. FastMCP includes support for multiple storage backends, and you can easily extend it with custom implementations.
> **Tip:** The storage layer is powered by **[py-key-value-aio](https://github.com/strawgate/py-key-value)**, an async key-value library maintained by a core FastMCP maintainer. This library provides a unified interface for multiple backends, making it easy to swap implementations based on your deployment needs.
## Available Backends
### In-Memory Storage
**Best for:** Development, testing, single-process deployments
In-memory storage is the default for all FastMCP storage needs. It's fast, requires no setup, and is perfect for getting started.
```python
from key_value.aio.stores.memory import MemoryStore
# Used by default - no configuration needed
# But you can also be explicit:
cache_store = MemoryStore()
```
**Characteristics:**
* ✅ No setup required
* ✅ Very fast
* ❌ Data lost on restart
* ❌ Not suitable for multi-process deployments
### Disk Storage
**Best for:** Single-server production deployments, persistent caching
Disk storage persists data to the filesystem, allowing it to survive server restarts.
```python
from key_value.aio.stores.disk import DiskStore
from fastmcp.server.middleware.caching import ResponseCachingMiddleware
# Persistent response cache
middleware = ResponseCachingMiddleware(
cache_storage=DiskStore(directory="/var/cache/fastmcp")
)
```
Or with OAuth token storage:
```python
from fastmcp.server.auth.providers.github import GitHubProvider
from key_value.aio.stores.disk import DiskStore
auth = GitHubProvider(
client_id="your-id",
client_secret="your-secret",
base_url="https://your-server.com",
client_storage=DiskStore(directory="/var/lib/fastmcp/oauth")
)
```
**Characteristics:**
* ✅ Data persists across restarts
* ✅ Good performance for moderate load
* ❌ Not suitable for distributed deployments
* ❌ Filesystem access required
### Redis
**Best for:** Distributed production deployments, shared caching across multiple servers
> **Note:** Redis support requires an optional dependency: `pip install 'py-key-value-aio[redis]'`
Redis provides distributed caching and state management, ideal for production deployments with multiple server instances.
```python
from key_value.aio.stores.redis import RedisStore
from fastmcp.server.middleware.caching import ResponseCachingMiddleware
# Distributed response cache
middleware = ResponseCachingMiddleware(
cache_storage=RedisStore(host="redis.example.com", port=6379)
)
```
With authentication:
```python
from key_value.aio.stores.redis import RedisStore
cache_store = RedisStore(
host="redis.example.com",
port=6379,
password="your-redis-password"
)
```
For OAuth token storage:
```python
import os
from fastmcp.server.auth.providers.github import GitHubProvider
from key_value.aio.stores.redis import RedisStore
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", port=6379)
)
```
**Characteristics:**
* ✅ Distributed and highly available
* ✅ Fast in-memory performance
* ✅ Works across multiple server instances
* ✅ Built-in TTL support
* ❌ Requires Redis infrastructure
* ❌ Network latency vs local storage
### Other Backends from py-key-value-aio
The py-key-value-aio library includes additional implementations for various storage systems:
* **DynamoDB** - AWS distributed database
* **MongoDB** - NoSQL document store
* **Elasticsearch** - Distributed search and analytics
* **Memcached** - Distributed memory caching
* **RocksDB** - Embedded high-performance key-value store
* **Valkey** - Redis-compatible server
For configuration details on these backends, consult the [py-key-value-aio documentation](https://github.com/strawgate/py-key-value).
> **Warning:** Before using these backends in production, review the [py-key-value documentation](https://github.com/strawgate/py-key-value) to understand the maturity level and limitations of your chosen backend. Some backends may be in preview or have specific constraints that make them unsuitable for production use.
## Use Cases in FastMCP
### Server-Side OAuth Token Storage
The OAuth Proxy and OAuth auth providers use storage for persisting OAuth client registrations and upstream tokens. **By default, storage is automatically encrypted using `FernetEncryptionWrapper`.** When providing custom storage, wrap it in `FernetEncryptionWrapper` to encrypt sensitive OAuth tokens at rest.
**Development (default behavior):**
By default, FastMCP automatically manages keys and storage based on your platform:
* **Mac/Windows**: Keys are auto-managed via system keyring, storage defaults to disk. Suitable **only** for development and local testing.
* **Linux**: Keys are ephemeral, storage defaults to memory.
No configuration needed:
```python
from fastmcp.server.auth.providers.github import GitHubProvider
auth = GitHubProvider(
client_id="your-id",
client_secret="your-secret",
base_url="https://your-server.com"
)
```
**Production:**
For production deployments, configure explicit keys and persistent network-accessible storage with encryption:
```python
import os
from fastmcp.server.auth.providers.github import GitHubProvider
from key_value.aio.stores.redis import RedisStore
from key_value.aio.wrappers.encryption import FernetEncryptionWrapper
from cryptography.fernet import Fernet
auth = GitHubProvider(
client_id=os.environ["GITHUB_CLIENT_ID"],
client_secret=os.environ["GITHUB_CLIENT_SECRET"],
base_url="https://your-server.com",
# Explicit JWT signing key (required for production)
jwt_signing_key=os.environ["JWT_SIGNING_KEY"],
# Encrypted persistent storage (required for production)
client_storage=FernetEncryptionWrapper(
key_value=RedisStore(host="redis.example.com", port=6379),
fernet=Fernet(os.environ["STORAGE_ENCRYPTION_KEY"])
)
)
```
Both parameters are required for production. **Wrap your storage in `FernetEncryptionWrapper` to encrypt sensitive OAuth tokens at rest** - without it, tokens are stored in plaintext. See OAuth Token Security and Key and Storage Management for complete setup details.
### Response Caching Middleware
The Response Caching Middleware caches tool calls, resource reads, and prompt requests. Storage configuration is passed via the `cache_storage` parameter:
```python
from fastmcp import FastMCP
from fastmcp.server.middleware.caching import ResponseCachingMiddleware
from key_value.aio.stores.disk import DiskStore
mcp = FastMCP("My Server")
# Cache to disk instead of memory
mcp.add_middleware(ResponseCachingMiddleware(
cache_storage=DiskStore(directory="cache")
))
```
For multi-server deployments sharing a Redis instance:
```python
from fastmcp.server.middleware.caching import ResponseCachingMiddleware
from key_value.aio.stores.redis import RedisStore
from key_value.aio.wrappers.prefix_collections import PrefixCollectionsWrapper
base_store = RedisStore(host="redis.example.com")
namespaced_store = PrefixCollectionsWrapper(
key_value=base_store,
prefix="my-server"
)
middleware = ResponseCachingMiddleware(cache_storage=namespaced_store)
```
### Client-Side OAuth Token Storage
The FastMCP Client uses storage for persisting OAuth tokens locally. By default, tokens are stored in memory:
```python
from fastmcp.client.auth import OAuthClientProvider
from key_value.aio.stores.disk import DiskStore
# Store tokens on disk for persistence across restarts
token_storage = DiskStore(directory="~/.local/share/fastmcp/tokens")
oauth_provider = OAuthClientProvider(
mcp_url="https://your-mcp-server.com/mcp/sse",
token_storage=token_storage
)
```
This allows clients to reconnect without re-authenticating after restarts.
## Choosing a Backend
| Backend | Development | Single Server | Multi-Server | Cloud Native |
| -------- | ----------- | ------------- | ------------ | ------------ |
| Memory | ✅ Best | ⚠️ Limited | ❌ | ❌ |
| Disk | ✅ Good | ✅ Recommended | ❌ | ⚠️ |
| Redis | ⚠️ Overkill | ✅ Good | ✅ Best | ✅ Best |
| DynamoDB | ❌ | ⚠️ | ✅ | ✅ Best (AWS) |
| MongoDB | ❌ | ⚠️ | ✅ | ✅ Good |
**Decision tree:**
1. **Just starting?** Use **Memory** (default) - no configuration needed
2. **Single server, needs persistence?** Use **Disk**
3. **Multiple servers or cloud deployment?** Use **Redis** or **DynamoDB**
4. **Existing infrastructure?** Look for a matching py-key-value-aio backend
## More Resources
* [py-key-value-aio GitHub](https://github.com/strawgate/py-key-value) - Full library documentation
* Response Caching Middleware - Using storage for caching
* OAuth Token Security - Production OAuth configuration
* HTTP Deployment - Complete deployment guide
> ## Documentation Index
> Fetch the complete documentation index at: https://gofastmcp.com/llms.txt
> Use this file to discover all available pages before exploring further.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |