URL: https://gofastmcp.com/servers/storage-backends
Title: Storage Backends - FastMCP

Documentation Index
Fetch the complete documentation index at:
/llms.txt
Use this file to discover all available pages before exploring further.
Skip to main content
Meet
Prefect Horizon
, the enterprise MCP gateway built by the team behind FastMCP
FastMCP
home page
v3
Prefect Horizon
PrefectHQ/fastmcp
25,596
PrefectHQ/fastmcp
25,596
Search...
Navigation
Extensibility
Storage Backends
Search the docs...
Ctrl
K
Documentation
Get Started
Welcome!
Installation
Quickstart
Servers
Overview
Core Components
Working with Tools
MCP Providers
Interactivity
Extensibility
Middleware
Dependencies
NEW
Lifespan
NEW
Storage Backends
NEW
Background Tasks
NEW
Versioning
NEW
Auth
Deployment
Apps
Overview
Quickstart
NEW
FastMCPApp
NEW
Interactive Tools
NEW
Generative UI
NEW
Custom HTML
Reference
Clients
Overview
Client-Only Package
Transports
fastmcp-remote
Operations
UPDATED
Authentication
UPDATED
Integrations
Auth
Web Frameworks
AI Assistants
AI SDKs
MCP.json
More
Settings
CLI
Upgrading
Development
What's New
FAQ
On this page
Available Backends
In-Memory Storage
File Storage
Redis
Other Backends from py-key-value-aio
Use Cases in FastMCP
Server-Side OAuth Token Storage
Response Caching Middleware
Client-Side OAuth Token Storage
Choosing a Backend
More Resources
Extensibility
Storage Backends
Copy page
Configure persistent and distributed storage for caching and OAuth state management
Copy page
New in version
2.13.0
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.
The storage layer is powered by
py-key-value-aio
, 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.
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
​
File Storage
Best for:
Single-server production deployments, persistent caching
File storage persists data to the filesystem as one JSON file per key, allowing it to survive server restarts. This is the default backend for OAuth storage on Mac and Windows.
from
pathlib
import
Path
from
key_value
.
aio
.
stores
.
filetree
import
(
FileTreeStore
,
FileTreeV1KeySanitizationStrategy
,
FileTreeV1CollectionSanitizationStrategy
,
)
from
fastmcp
.
server
.
middleware
.
caching
import
ResponseCachingMiddleware
storage_dir
=
Path
(
"
/var/cache/fastmcp
"
)
store
=
FileTreeStore
(
data_directory
=
storage_dir
,
key_sanitization_strategy
=
FileTreeV1KeySanitizationStrategy
(
storage_dir
),
collection_sanitization_strategy
=
FileTreeV1CollectionSanitizationStrategy
(
storage_dir
),
)
# Persistent response cache
middleware
=
ResponseCachingMiddleware
(
cache_storage
=
store
)
Sanitization strategies are required
when using
FileTreeStore
. Without them, keys containing special characters (such as URL-based OAuth client IDs like
https://claude.ai/oauth/claude-code-client-metadata
) will be used as-is in filesystem paths, causing
FileNotFoundError
crashes. The V1 strategies shown above are safe defaults — alphanumeric names pass through as-is for readability, while special characters are hashed to prevent path errors and traversal attacks. Changing sanitization strategies after data has been written is a breaking change, so choose your strategy upfront.
Characteristics:
✅ Data persists across restarts
✅ No external dependencies
✅ Human-readable files on disk
❌ Not suitable for distributed deployments
❌ Filesystem access required
​
Redis
Best for:
Distributed production deployments, shared caching across multiple servers
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.
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:
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:
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
.
Before using these backends in production, review the
py-key-value documentation
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:
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:
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:
from
pathlib
import
Path
from
fastmcp
import
FastMCP
from
fastmcp
.
server
.
middleware
.
caching
import
ResponseCachingMiddleware
from
key_value
.
aio
.
stores
.
filetree
import
(
FileTreeStore
,
FileTreeV1KeySanitizationStrategy
,
FileTreeV1CollectionSanitizationStrategy
,
)
mcp
=
FastMCP
(
"
My Server
"
)
cache_dir
=
Path
(
"
cache
"
)
cache_store
=
FileTreeStore
(
data_directory
=
cache_dir
,
key_sanitization_strategy
=
FileTreeV1KeySanitizationStrategy
(
cache_dir
),
collection_sanitization_strategy
=
FileTreeV1CollectionSanitizationStrategy
(
cache_dir
),
)
# Cache to disk instead of memory
mcp
.
add_middleware
(
ResponseCachingMiddleware
(
cache_storage
=
cache_store
))
For multi-server deployments sharing a Redis instance:
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:
from
pathlib
import
Path
from
fastmcp
.
client
.
auth
import
OAuth
from
key_value
.
aio
.
stores
.
filetree
import
(
FileTreeStore
,
FileTreeV1KeySanitizationStrategy
,
FileTreeV1CollectionSanitizationStrategy
,
)
# Store tokens on disk for persistence across restarts
token_dir
=
Path
(
"
~/.local/share/fastmcp/tokens
"
).
expanduser
()
token_storage
=
FileTreeStore
(
data_directory
=
token_dir
,
key_sanitization_strategy
=
FileTreeV1KeySanitizationStrategy
(
token_dir
),
collection_sanitization_strategy
=
FileTreeV1CollectionSanitizationStrategy
(
token_dir
),
)
oauth_provider
=
OAuth
(
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
❌
❌
File
✅ Good
✅ Recommended
❌
⚠️
Redis
⚠️ Overkill
✅ Good
✅ Best
✅ Best
DynamoDB
❌
⚠️
✅
✅ Best (AWS)
MongoDB
❌
⚠️
✅
✅ Good
Decision tree:
Just starting?
Use
Memory
(default) - no configuration needed
Single server, needs persistence?
Use
File
Multiple servers or cloud deployment?
Use
Redis
or
DynamoDB
Existing infrastructure?
Look for a matching py-key-value-aio backend
​
More Resources
py-key-value-aio GitHub
- Full library documentation
Response Caching Middleware
- Using storage for caching
OAuth Token Security
- Production OAuth configuration
HTTP Deployment
- Complete deployment guide
Lifespans
Previous
Background Tasks
Next
Ctrl
+I
discord
github
website
x
Powered by
This documentation is built and hosted on Mintlify, a developer documentation platform
Assistant
Responses are generated using AI and may contain mistakes.
\n\n
\n
\n \n
\n
