Skip to content

docs: redis-session-storage guide only covers auth server — add section for MCPServer/VirtualMCPServer horizontal scaling Redis setup #707

@yrobla

Description

@yrobla

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:

  1. Simple Redis deployment for the scaling use case (no Sentinel required for basic setups; a standalone Redis with a password is sufficient)
  2. Creating the Kubernetes Secret for the passwordRef field:
    kubectl create secret generic redis-secret \
      --namespace <NAMESPACE> \
      --from-literal=password="YOUR_REDIS_PASSWORD"
  3. Full working MCPServer example wiring sessionStorage to the Redis Secret
  4. Full working VirtualMCPServer example doing the same
  5. 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.)
  6. Verification steps: how to confirm Redis-backed session sharing is working (check SessionStorageWarning=False condition, check pod logs, test cross-pod session reconstruction)
  7. 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)

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions