Skip to content

Document session affinity #593

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
eleftherias wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Document session affinity #593

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
a83ce21
Document session affinity
eleftherias Mar 6, 2026
a5d6668
Merge branch 'main' into session-affinity
eleftherias Mar 6, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 10 additions & 2 deletions docs/toolhive/guides-vmcp/scaling-and-performance.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -65,10 +65,18 @@ However, **stateful backends** make horizontal scaling difficult:
- **Stateful backends** (Playwright browser sessions, database connections, file
system operations) require requests to be routed to the same vMCP instance
that established the session
- Requires session affinity configuration (which may not work reliably through
proxies)
- Session resumption may not work reliably for stateful backends

The `VirtualMCPServer` CRD includes a `sessionAffinity` field that controls how
the Kubernetes Service routes repeated client connections. By default, it uses
`ClientIP` affinity, which routes connections from the same client IP to the
same pod. You can configure this using the `sessionAffinity` field:

```yaml
spec:
sessionAffinity: ClientIP # default
```
Comment on lines +70 to +78
Copy link

Copilot AI Mar 6, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The docs state that the VirtualMCPServer CRD has a spec.sessionAffinity field with default ClientIP, but I can’t find sessionAffinity anywhere in the CRD reference (docs/toolhive/reference/crd-spec.md) or in the repo’s Go/YAML sources. This makes the configuration example misleading. Please either (a) update the operator/CRD and reference docs to actually support this field, or (b) reword this section to describe how to set spec.sessionAffinity on the generated Kubernetes Service (if that’s the intended approach) and clarify the actual default behavior.

Copilot uses AI. Check for mistakes.

For stateful backends, vertical scaling or dedicated vMCP instances per team/use
case are recommended instead of horizontal scaling.

Expand Down