Skip to main content
@phake/mcp uses two kinds of stores:
  • Token stores (TokenStore) — persist RS token ↔ provider token mappings, OAuth transactions, and authorization codes. Used by the OAuth flow.
  • Session stores (SessionStore) — track active MCP sessions, their API keys, and initialization state.
Both store types share the same interface regardless of backend, so you can swap between them without changing tool code.

​
Available backends

BackendKindUse caseNotes
KvTokenStoreTokenTokens, transactions, codesCloudflare KV + memory fallback, AES-256-GCM encryption
KvSessionStoreSessionSessionsCloudflare KV + memory fallback, AES-256-GCM encryption, API-key indexing
MemoryTokenStoreTokenTokens, transactions, codesTTL expiration, 10K token limit, LRU eviction
MemorySessionStoreSessionSessionsTTL (24 h), 10K session limit, 5 sessions per API key
FileTokenStoreTokenRS token mappingsFile persistence, AES-256-GCM encryption — experimental
SqliteSessionStoreSessionSessionsSQLite + Drizzle ORM, WAL mode — experimental

​
KV backends

KvTokenStore and KvSessionStore are the recommended backends for Cloudflare Workers deployments. They use the TOKENS KV namespace binding and encrypt every value at rest with AES-256-GCM before writing to KV. Both classes use an in-memory MemoryTokenStore / MemorySessionStore as a write-through fallback. If a KV write fails (for example, due to quota), the data remains accessible in memory for the lifetime of the Worker instance.

​
KvTokenStore

Stores RS token mappings, OAuth transactions, and authorization codes in Cloudflare KV.
createMCPServer wires up KvTokenStore automatically from your environment bindings. You only need to reference it directly if you are building a custom server assembly.
Token entries use automatic KV TTL expiration: transactions and authorization codes expire after 10 minutes.

​
KvSessionStore

Stores MCP session records in Cloudflare KV with a 24-hour TTL. Maintains a secondary index so sessions can be looked up by API key. Enforces a limit of 5 active sessions per API key, evicting the least-recently-accessed session when the limit is exceeded.

​
Encryption

Both KV backends encrypt every value with AES-256-GCM when RS_TOKENS_ENC_KEY is set in your environment. To generate a 32-byte key: 
openssl rand -base64 32 | tr '+/' '-_' | tr -d '='
Set the key as a Wrangler secret in production: 
wrangler secret put RS_TOKENS_ENC_KEY
# paste the generated key when prompted
Or add it to .dev.vars for local development: 
RS_TOKENS_ENC_KEY=<your-generated-key>

​
Memory backends

MemoryTokenStore and MemorySessionStore store data in process memory. They are suitable for local development, testing, and Node.js deployments where you don’t need cross-instance persistence.
Memory backends do not survive process restarts. All tokens and sessions are lost when the process exits. Do not use them as the sole storage layer in production if session persistence is required.
Both classes run a cleanup interval every 60 seconds to remove expired entries.

​
MemoryTokenStore

LimitValue
Maximum RS token records10,000
Maximum concurrent transactions1,000
RS token TTL7 days
Transaction TTL10 minutes
Authorization code TTL10 minutes
Eviction policyLRU (oldest entries removed first when limit reached)

​
MemorySessionStore

LimitValue
Maximum total sessions10,000
Maximum sessions per API key5
Session TTL24 hours
Eviction policyLRU (least-recently-accessed session evicted per API key when limit reached)

​
Experimental backends

The following backends are marked experimental. Their APIs may change between minor versions.

​
FileTokenStore

Persists RS token mappings to a JSON file on disk with AES-256-GCM encryption. Intended for Node.js deployments that need simple token persistence without a database. Configure the file path with RS_TOKENS_FILE: 
RS_TOKENS_FILE=./data/tokens.enc
RS_TOKENS_ENC_KEY=<your-key>

​
SqliteSessionStore

Stores sessions in a SQLite database using Drizzle ORM in WAL mode. Provides durable session persistence for Node.js deployments with better concurrency than the file-based store. Import from the Node.js runtime package: 
import { SqliteSessionStore } from "@phake/mcp/runtime/node";

​
Choosing a backend

Cloudflare Workers

Use KvTokenStore + KvSessionStore. Bind a KV namespace named TOKENS and set RS_TOKENS_ENC_KEY. The scaffolded templates configure this for you.

Node.js (development)

Use MemoryTokenStore + MemorySessionStore. No configuration needed — data lives in process memory.

Node.js (production)

Use FileTokenStore (experimental) for tokens and SqliteSessionStore (experimental) for sessions, or integrate your own stores by implementing the TokenStore and SessionStore interfaces.

Custom backend

Implement the TokenStore and/or SessionStore interfaces from @phake/mcp to use any storage system you choose.