Problem
guides-k8s/redis-session-storage.mdx acknowledges that Redis is required for horizontal scaling of MCPServer and VirtualMCPServer replicas, but its entire content covers only the embedded auth server Redis setup (Redis Sentinel + ACL auth model).
The two use cases use different Redis auth models:
- Auth server: ACL username + password, Sentinel service discovery,
thv:auth:* key pattern
- MCPServer/VirtualMCPServer session storage: simple
passwordRef (password only, no ACL username), direct address, user-specified keyPrefix
A user who wants to scale MCPServer or VirtualMCPServer horizontally follows the link from the scaling docs to redis-session-storage.mdx and finds a guide that does not apply to their use case — the ACL user defined there (toolhive-auth with ~thv:auth:* key pattern) will not work with the sessionStorage.passwordRef config in MCPServer/VirtualMCPServer.
What's needed
Add a new section to redis-session-storage.mdx (or a new page) that covers setting up Redis specifically for MCPServer/VirtualMCPServer horizontal scaling session storage. It should cover:
- Simple Redis deployment for the scaling use case (no Sentinel required for basic setups; a standalone Redis with a password is sufficient)
- Creating the Kubernetes Secret for the
passwordRef field:
kubectl create secret generic redis-secret \
--namespace <NAMESPACE> \
--from-literal=password="YOUR_REDIS_PASSWORD"
- Full working MCPServer example wiring
sessionStorage to the Redis Secret
- Full working VirtualMCPServer example doing the same
- Clarification: can the same Redis instance be reused for both auth server sessions and MCPServer/VirtualMCPServer sessions? (Answer: yes, using different
keyPrefix values and/or different Redis databases.)
- Verification steps: how to confirm Redis-backed session sharing is working (check
SessionStorageWarning=False condition, check pod logs, test cross-pod session reconstruction)
- Link from both
run-mcp-k8s.mdx#horizontal-scaling and scaling-and-performance.mdx#session-storage-for-multi-replica-deployments to this section/page
References
guides-k8s/run-mcp-k8s.mdx#horizontal-scaling — inline sessionStorage YAML snippet but no Redis setup steps
guides-vmcp/scaling-and-performance.mdx#session-storage-for-multi-replica-deployments — same inline snippet
guides-k8s/redis-session-storage.mdx — existing guide (auth server only)
- CRD ref:
api.v1alpha1.SessionStorageConfig
- Epic: stacklok/stacklok-epics#262 (Horizontal Scaling for vMCP, THV-0047)
Problem
guides-k8s/redis-session-storage.mdxacknowledges that Redis is required for horizontal scaling of MCPServer and VirtualMCPServer replicas, but its entire content covers only the embedded auth server Redis setup (Redis Sentinel + ACL auth model).The two use cases use different Redis auth models:
thv:auth:*key patternpasswordRef(password only, no ACL username), direct address, user-specifiedkeyPrefixA user who wants to scale
MCPServerorVirtualMCPServerhorizontally follows the link from the scaling docs toredis-session-storage.mdxand finds a guide that does not apply to their use case — the ACL user defined there (toolhive-authwith~thv:auth:*key pattern) will not work with thesessionStorage.passwordRefconfig in MCPServer/VirtualMCPServer.What's needed
Add a new section to
redis-session-storage.mdx(or a new page) that covers setting up Redis specifically for MCPServer/VirtualMCPServer horizontal scaling session storage. It should cover:passwordReffield:sessionStorageto the Redis SecretkeyPrefixvalues and/or different Redis databases.)SessionStorageWarning=Falsecondition, check pod logs, test cross-pod session reconstruction)run-mcp-k8s.mdx#horizontal-scalingandscaling-and-performance.mdx#session-storage-for-multi-replica-deploymentsto this section/pageReferences
guides-k8s/run-mcp-k8s.mdx#horizontal-scaling— inlinesessionStorageYAML snippet but no Redis setup stepsguides-vmcp/scaling-and-performance.mdx#session-storage-for-multi-replica-deployments— same inline snippetguides-k8s/redis-session-storage.mdx— existing guide (auth server only)api.v1alpha1.SessionStorageConfig