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

​
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:
Set the key as a Wrangler secret in production:
Or add it to .dev.vars for local development:

​
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

​
MemorySessionStore

​
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:

​
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:

​
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.