RFC: Session-Scoped Architecture for vMCP

[yrobla]

RFC: Session-Scoped Architecture for vMCP

This RFC refactors vMCP session management to fix per-request client creation and scattered session concerns.

Problem

• Per-request overhead: Backend clients created/closed on every tool call, causing connection overhead and state loss for stateful
  backends (Playwright, databases)
• Scattered architecture: Session creation tangled across middleware, adapters, and SDK hooks with no clear ownership
• Hard to extend: Current design makes it difficult to add features (optimizer-in-vmcp) or write integration tests without spinning up
  the full server

Solution

Introduce two core interfaces:

1. Session - Domain object that owns backend clients, encapsulates routing logic, manages lifecycle
2. SessionFactory - Creates fully-formed sessions (capability discovery + client initialization)
3. SessionManager - Bridges domain logic to SDK protocol concerns

Key improvement: Clients created once during session init, reused for all requests, closed on expiration.

[Copilot]

Pull request overview

Adds an RFC proposing a shift from per-request/lazy MCP backend client creation to session-scoped client lifecycle management to simplify the current pooling approach while preserving backend state across tool calls.

Changes:

• Introduces a new RFC describing a session-scoped backend client map owned by VMCPSession.
• Specifies eager client initialization during session setup (AfterInitialize) and cleanup during session close.
• Outlines phased implementation steps, testing strategy, and alternatives considered.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

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

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

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

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

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

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[jerm-dro]

I left two bigger comments elaborating on my thoughts. To summarize, I think there are larger problems with how the session concept is handled within vMCP. Namely, we have session concerns scattered throughout the codebase and all of these concerns are tightly coupled. As a solution, I think we should create an interface that encapsulates these concerns:

// Session represents an active MCP session with all its capabilities and resources.
// This is a pure domain object - no protocol concerns and can be run without being spun up in a server.
type Session interface {
    ID() string

    // Capabilities - returns discovered tools/resources for this session
    // Perhaps these could be combined into one "GetCapabilities" method.
    Tools() []Tool
    Resources() []Resource

    // MCP operations - routing logic is encapsulated here
    CallTool(ctx context.Context, name string, arguments map[string]any) (*ToolResult, error)
    ReadResource(ctx context.Context, uri string) (*ResourceResult, error)
    GetPrompt(ctx context.Context, name string, arguments map[string]any) (*PromptResult, error)

    // Lifecycle
    Close() error
}

That would make solving this client-lifetime problem trivial.

[Copilot]

Pull request overview

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

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[jerm-dro]

@JAORMX Thanks for the review and context around transportsession.Manager!

I'm not opposed to preserving the existing session storage mechanism as part of this work. The main thrust of this RFC is encapsulating the session concept and behavior into a coherent domain object, and, based on my read of the code, that can still be accomplished without changing the storage mechanism.

That said, it's worth acknowledging that we're currently paying a cognitive cost to maintain the storage abstraction layer ahead of a distributed backend that doesn't exist yet. I'd be curious to hear your thoughts on the timeline for that work, since it would help us calibrate how much we invest in preserving compatibility with it right now vs. keeping things simple.

In the future, I also think it's worth exploring whether we can simplify the transportsession.Manager API. For example, rather than the current get/set pattern on the Manager, an alternative factoring could have the Session object become the sole owner of its state and expose a Marshal() method that produces a serialized representation on demand. That would make the ownership of data clearer and the storage layer thinner. But that's beyond the scope of this RFC and something we can think through at a later date. When we design this in earnest, we should think deeper about what state can change, when it changes how we signal to update its stored representation, etc.

[Copilot]

Pull request overview

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

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[JAORMX]

Thanks for addressing the feedback, Yolanda! The integration with transportsession.Manager (instead of a parallel sync.Map), the dual-layer storage model (metadata vs. runtime), and the composition model (defaultSession embedding transportsession.Session) all look good. This preserves the Redis/Valkey externalization path we built out in #1677/#1989/#1770/#1771 while delivering the session encapsulation improvements.

LGTM!

[jerm-dro]

The changes motivated by others' feedback LGTM.

[yrobla]

Different advices collected:

• one different session per vmcp per client, how it will affect the current RFC - that's a problem with the transport and single endpoint
• sessions in one mcp can terminate before others
• investigate if we could replace this with Stateful Streamable HTTP, and will be the implementation that is needed. Can we assume that all MCP servers support it?
• we can create a test suite to validate that on multiple clients - but this should also be better done at MCP level, and we could reuse for vMCP

[Copilot]

Pull request overview

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

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

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

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

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

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.