Add horizontal scaling Redis session storage guide

[yrobla]

Summary

The existing redis-session-storage page only covered the embedded auth server's Redis setup (Sentinel + ACL). Users who want to scale MCPServer or VirtualMCPServer horizontally were sent to this page but the auth model is completely different — sessionStorage.passwordRef uses a simple password with no ACL username or Sentinel.

• Restructures redis-session-storage.mdx into two named sections with a clear intro explaining which section applies to which use case
• Adds a new Horizontal scaling session storage section with: standalone Redis Deployment/Service/Secret manifests, full MCPServer and VirtualMCPServer sessionStorage YAML examples, verification steps (checking SessionStorageWarning condition + manual cross-pod test), and a Sharing a Redis instance guide using keyPrefix to multiplex the two use cases on a single Redis instance
• Updates run-mcp-k8s.mdx and scaling-and-performance.mdx to link directly to the new #horizontal-scaling-session-storage anchor instead of the top of the page

Test plan

• Preview renders correctly in Docusaurus (section anchors, YAML code blocks, admonitions, table)
• Links from run-mcp-k8s.mdx#horizontal-scaling and scaling-and-performance.mdx#session-storage-for-multi-replica-deployments resolve to the correct anchor
• CRD ref links at the bottom resolve correctly

Closes #707

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
docs-website	Ready	Preview, Comment	Apr 14, 2026 1:33pm

[Copilot]

Pull request overview

Updates the Redis session storage documentation so it clearly differentiates between the embedded auth server Redis setup and the Redis setup required to horizontally scale MCPServer / VirtualMCPServer replicas.

Changes:

• Restructures redis-session-storage.mdx into separate sections for embedded auth server storage vs horizontal scaling session storage.
• Adds a new horizontal-scaling Redis deployment + MCPServer / VirtualMCPServer sessionStorage examples and verification guidance.
• Updates scaling guides to deep-link directly to the new horizontal-scaling section anchor.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 4 comments.

File	Description
docs/toolhive/guides-vmcp/scaling-and-performance.mdx	Updates the Redis session storage link to point directly to the horizontal-scaling section anchor.
docs/toolhive/guides-k8s/run-mcp-k8s.mdx	Updates the Redis session storage link to point directly to the horizontal-scaling section anchor.
docs/toolhive/guides-k8s/redis-session-storage.mdx	Renames/reframes the page and adds a new horizontal scaling Redis session storage section, including manifests, examples, and verification steps.

[Copilot]

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.

[danbarr]

Editorial review

This is a well-motivated restructuring. The existing page only covered the embedded auth server's Sentinel setup, leaving readers sent here for horizontal scaling confused by irrelevant ACL/Sentinel configuration. Splitting into two clearly labeled sections with a shared-instance bridge is the right architecture. The link updates in the other two files are correct. CRD reference anchors verified.

Issues

1. Em dashes throughout (style guide violation)

Seven em dashes in the new content. All need to be rephrased or replaced with spaced hyphens per the style guide. Listing them by location:

• Intro bullets (3): "Embedded authorization server sessions — stores...", "...horizontal scaling — shares...", "databases — see [Sharing...]"
• Section intro: "a simple password — no ACL user, no Sentinel"
• Verification section: "your client will need to reconnect — but if Redis..."
• ACL section: "a passwordRef — no username field — so it always..."
• Note: "SessionStorageConfig does not support Sentinel — it uses..."

The three intro bullets are list-style context, so spaced hyphens work. The others should be rephrased into separate clauses or sentences.

2. En dash in "0-15"

Alternatively, use separate db values (Redis databases 0–15)

Uses an en dash. Replace with a hyphen: 0-15.

3. Front matter description starts with filler

How to deploy Redis Sentinel with persistent storage for the ToolHive embedded authorization server, and a standalone Redis instance for horizontal scaling of MCPServer and VirtualMCPServer.

The style guide says to lead with the action or topic, not filler like "How to." Also, this is 171 characters - fine for SEO, but the first 70 characters ("How to deploy Redis Sentinel with persistent storage for the ToolHive") cut off mid-thought for DocCard previews. Consider:

Deploy Redis Sentinel for the ToolHive embedded auth server, or a standalone Redis instance for MCPServer and VirtualMCPServer horizontal scaling.

This leads with the verb, and the first ~70 characters carry more meaning in DocCard previews.

4. Awkward phrasing in the intro

ToolHive uses Redis in several places. Two of them use different configuration models and are covered on this page:

"Two of them" is vague - "them" refers to "places" which reads oddly. Suggestion:

ToolHive uses Redis for several purposes. This page covers two that require different configuration:

5. Verification section: "absent or set to False" is ambiguous

When Redis is properly configured, the SessionStorageWarning condition is absent or set to False:

The example output that follows shows the condition present with Status: False. If the condition can be absent entirely, that's a different state the reader won't see in kubectl describe output. Either clarify when each state occurs, or just say "set to False" since that's what the example shows.

Minor suggestions

• Semicolon in intro bullet: "Session data is not persisted to disk; if the Redis pod restarts, active sessions are lost and clients must reconnect." - Two sentences would be easier to scan.

• "Sharing a Redis instance" placement: This H3 lives under "## Horizontal scaling session storage" but conceptually bridges both sections. Consider promoting it to an H2 so it's visually parallel. Not blocking - the current placement is functional since the reader is likely arriving from the scaling use case.

• ACL subsection heading: "ACL configuration for a shared instance" is an H3 nested under the scaling H2, but it's really a sub-topic of "Sharing a Redis instance" (also H3). Consider making it an H4 to reflect the hierarchy, or fold it into the sharing section.

What works well

• The intro with two clearly differentiated bullets and anchor links is excellent wayfinding for a page that now serves two audiences.
• The "Sharing a Redis instance" section with the keyPrefix table is practical and addresses the obvious follow-up question.
• The cross-pod verification test procedure is concrete and actionable.
• Link updates in the other two files correctly point to the new anchor and use descriptive link text.
• Horizontal rules between the major sections provide a clear visual break.