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
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions