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

Merged
danbarr merged 2 commits into from
Mar 16, 2026
Merged

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
```

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

Expand Down