stacklok / stacklok/toolhive

[vMCP] Implement optional backend session keepalive

Open
#3,870 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

api enhancement p1 telemetry vmcp
Dominant language
Go
Stars
2.2k
Forks
300
Avg merge
1d 15h
Merged PRs (30d)
184

Description

Depends on #3865

For stateful backends (e.g., Playwright, database connections), implement an optional keepalive mechanism to prevent backend session expiration while the corresponding vMCP session is active.

Implementation:

  • Prefer the MCP spec-defined ping protocol request (side-effect-free, supported by all compliant servers); fall back to an explicitly configured low-cost tool only if ping consistently fails
  • Per-backend configuration: keepalive_method: ping | tool:<name> | none; default: attempt ping
  • Configurable interval at server level (default ≥ 5 min); jitter keepalive calls across sessions to avoid spikes
  • The keepalive goroutine must acquire the session/backend lock before issuing calls to prevent races with reinitializeBackend
  • Circuit-breaker: after N consecutive failures, disable keepalive for that backend and log a warning; probe again after ~30 min to re-enable without requiring full session recreation
  • Disable by default for stateless backends and backends where TTL alignment already covers the session lifetime
Acceptance Criteria
  • Keepalive uses ping by default; falls back to configured tool only when ping fails
  • Keepalive is disabled when keepalive_method: none is set
  • The keepalive interval is configurable and defaults to ≥ 5 minutes
  • Keepalive calls across sessions are jittered to avoid synchronized spikes
  • The keepalive goroutine holds the appropriate lock before calling the backend
  • Keepalive failures do not surface as errors to the end user or fail the vMCP session
  • After N consecutive failures, keepalive is disabled for that backend with a logged warning
  • A probe after ~30 min re-enables keepalive if the backend recovers
  • Keepalive is disabled by default for stateless backends
  • Metrics are emitted: keepalive_attempt_count, keepalive_success_count, keepalive_failure_count (by reason), keepalive_latency_ms, keepalive_auto_disabled_total (by reason)
  • Unit tests cover: ping used by default, fallback to tool, circuit breaker, re-enable after probe, metrics emitted

RFC: THV-0038 — Session-scoped client lifecycle

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reading the prerequisite issue #3865 and the linked THV-0038 session-scoped client lifecycle RFC to locate the vMCP session and backend lifecycle entry points. Define the keepalive configuration, scheduling and locking behavior there, then use the acceptance criteria as the completion checklist, including circuit-breaker recovery, metrics, and unit tests.

Written by the indexing model from the issue text.

Assessment

Tech stack
go
Domain
backend
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.