Feature request: Multi-session support for parallel browser instances

[RobertWsp]

Problem

The current MCP server binds to a single Chrome instance for its entire lifetime. This means any MCP client (AI agent, test runner, automation script) can only interact with one browser at a time. To work with multiple browsers, users must start multiple MCP server processes and manage them externally.

Use Cases

1. AI agents researching multiple sources in parallel

This is the most natural use case given that the MCP server is designed for LLM integration. AI agents frequently need to:

• Open multiple documentation sites simultaneously to cross-reference information
• Search across different sources (GitHub, Stack Overflow, official docs) in parallel rather than sequentially
• Compare content across multiple URLs without losing page state

Today, the agent must navigate away from one page to visit another, losing all context. With multiple sessions, it can keep all pages alive and switch between them.

2. Multi-user interaction testing

Testing real-time collaborative features requires simulating multiple users:

• Chat applications: User A sends a message, verify User B receives it
• Collaborative editing: Two users editing the same document simultaneously
• Multiplayer flows: Testing turn-based or real-time interactions

Each user needs their own isolated browser with separate cookies, auth state, and session storage.

3. Authenticated vs unauthenticated comparison

Common debugging workflow:

• Session A: Logged in as admin
• Session B: Logged in as regular user
• Session C: Not logged in

Compare how the same page renders across different auth states without logging in/out repeatedly.

4. CI/CD parallel test execution

A single MCP server could serve multiple test runners in a CI pipeline, each getting its own isolated browser. This avoids the overhead of spawning N separate MCP server processes and N separate Chrome instances managed externally.

5. Cross-viewport testing

Simultaneously test the same page across different viewport configurations:

• Desktop (1920×1080)
• Tablet (768×1024)
• Mobile (375×812)

Each session runs with its own viewport settings, enabling side-by-side responsive testing.

Proposed API

A minimal approach:

Tool	Purpose
create_session	Launch a new Chrome instance, returns a unique sessionId
list_sessions	List active sessions with metadata
close_session	Shut down a specific session

All existing tools would accept an optional sessionId parameter. If omitted, a default/single session is used (fully backward compatible).

Prior Art

I have a working implementation in PR #899 that demonstrates this approach. Happy to iterate on the design based on feedback from this discussion.

Questions for Maintainers

• Are there specific use cases above that resonate more with your roadmap?
• Would you prefer a different API shape (e.g., session as a resource rather than a tool parameter)?
• Any concerns about resource management (max sessions, TTL, cleanup) that should be addressed upfront?

[natorion]

We have been discussing this a few times already. I would love to build up more conviction around this. I worry a bit, that AI agents will have a hard time understanding and utilizing sessions correctly. @matthiasrohmer thoughts?

[matthiasrohmer]

Thanks for the request and the PR, @RobertWsp! I shared this across social (Bluesky, X and LinkedIn) to learn a little more, @natorion.

I definitely see the use cases outlined. Can you tell what's your main driver for this proposal, @RobertWsp? It sounds like it would be resource optimization more than developer experience, but curious if that's really the case, and if yes are you looking at your local environment or cloud environments?

For 5. Cross-viewport testing an alternative might be exposing DevTools device mode capabilities to the MCP server - but less versatile and quite a lift I think.

[RobertWsp]

Thanks for sharing this and for the thoughtful question, @matthiasrohmer!

My main driver is developer experience, not resource optimization.

I use LLMs (Claude, GPT, Gemini) as development partners via MCP. My primary use case is working on real-time features over WebSocket — and today, the LLM simply cannot validate its own work in this context.

For example, I've been working on a CRM application that relies heavily on real-time communication (WebSocket). When the LLM implements a feature like a live chat or a real-time notification, it has no way to verify it actually works — because verifying real-time behavior requires two browsers open simultaneously, each authenticated as a different user, connected to the same WebSocket channel. With a single session, the LLM is blind to one side of the interaction.

With multi-session support, the LLM could:

1. Session A: Log in as User A, open the chat
2. Session B: Log in as User B, open the same chat
3. Session A: Send a message
4. Session B: Check that the message appeared in real time

This is not about traditional test automation — it's about giving the LLM the ability to interact with and validate real-time collaborative features during the development conversation. Today, this is simply not possible.

As for 5. Cross-viewport testing — I agree that DevTools device mode could cover responsive testing within a single session. The multi-session angle there is more about parallelism: the LLM could spin up multiple sessions and validate the same feature across different viewports simultaneously rather than one at a time. Not a blocker, just a nice capability that comes for free.

Regarding @natorion's concern about agents struggling with sessions — in my implementation and testing, the model handles it well since sessionId is just an opaque string returned by create_session and passed to every subsequent call. It's a pattern LLMs already understand from database connections, API tokens, etc.

Happy to provide a demo or more details if helpful!

[matthiasrohmer]

Got it, thank you for the clarification! Did you actively instruct your model to use multiple sessions when prompting? If yes an example prompt would be great.

I wonder if @natorion's concern is the reverse actually: might a model overly eagerly create new sessions (and Chrome instances) when it could just reuse an existing one. But an option to remedy could be to put multi-session behind a flag, and leave it for advanced users.

Anyway, really appreciate all the thought that went in to this. I'll reach out to some more people on the team, to learn what they think too ☺️

[jtimi-mtbk]

WOW 😮

[RobertWsp]

Yes, I instruct the model explicitly. Here's a real example of the kind of prompt I use during development:

I just implemented the live chat feature in the CRM.
Open two browser sessions:
- Session 1: Log in as admin@company.com, go to /chat
- Session 2: Log in as user@company.com, go to /chat
Then send a message from the admin and verify it shows up
on the user's side in real time.
Also check the network tab for WebSocket connections
and take screenshots of both sessions to visually confirm.

The model then does something like:

create_session(label: "admin")     → sessionId: "a1b2c3d4"
create_session(label: "user")      → sessionId: "e5f6g7h8"

navigate_page(sessionId: "a1b2c3d4", url: "http://localhost:3000/chat")
navigate_page(sessionId: "e5f6g7h8", url: "http://localhost:3000/chat")

// authenticate each session independently via fill + click

fill(sessionId: "a1b2c3d4", uid: "message-input", value: "Hello from admin!")
click(sessionId: "a1b2c3d4", uid: "send-button")

// verify the message arrived on the other side
take_snapshot(sessionId: "e5f6g7h8")           // check a11y tree for the message
take_screenshot(sessionId: "e5f6g7h8")         // visual confirmation
list_network_requests(sessionId: "e5f6g7h8")   // verify WebSocket connection is active

Without multi-session, the model can only log in as one user at a time and has no way to confirm the other side received anything.

Regarding the concern about models over-eagerly creating sessions — I think that's valid, and the flag idea is a great approach. In practice though, I've been using Claude Opus 4.6 and it only creates new sessions when explicitly asked to. It defaults to reusing the existing one for regular browsing. The sessionId being a required parameter on every tool call also makes it very intentional — the model has to consciously choose which session to target.

Thanks for pushing this forward with the team!

[OrKoN]

@RobertWsp do you know if the MCP sessions are of any use here https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#session-management? Generally, it should be possible to then implement sessions this way along with the HTTP transport if Claude Code and other clients would be able manage it it.

Alternatively, instead of creating a new browser instance we could use browser context (it is similar to incognito profiles) to have multiple isolated profiles within a single session. It would be faster than instantiating multiple browsers. Would that work as well?

[RobertWsp]

Great questions, @OrKoN — I investigated both suggestions in depth.

MCP Protocol Sessions (Mcp-Session-Id)

I looked into the MCP session management spec thoroughly. While all major MCP clients (Claude Code, Gemini CLI, OpenCode, Cursor) now support Streamable HTTP transport, there's a fundamental gap:

No client currently supports multiple concurrent Mcp-Session-Id sessions to the same server. They all follow a Record<string, MCPClient> pattern — one connection per server name. More critically, Mcp-Session-Id is an HTTP transport header, not a tool parameter. The LLM operates at the tool layer and has no mechanism to say "route this tool call to MCP session A vs MCP session B."

For protocol-level sessions to solve multi-browser use cases, clients would need:

1. Architecture to support multiple connections to the same MCP server
2. A way for the LLM to control which session a tool call is routed to

This is the right long-term direction, but not something we can rely on today.

BrowserContext — Yes, this is the way to go ✅

BrowserContext is an excellent suggestion and covers the real-time testing use case perfectly. I've refactored the implementation to use browser.createBrowserContext() instead of launching multiple Chrome instances. In Chrome, all non-default contexts are incognito — isolated cookies, localStorage, WebSocket connections, service workers — all within a single Chrome process, with instant creation and much lower memory overhead.

The implementation adds 3 session tools (create_session, list_sessions, close_session) and injects an optional sessionId parameter into every existing tool. When sessionId is omitted, tools work against the default browser context exactly as they do today — fully backward compatible, zero breaking changes.

I've E2E tested it with two simultaneous sessions performing independent DuckDuckGo searches — different queries, completely isolated results, separate cookies/state. Session creation is near-instant since it's just browser.createBrowserContext() + context.newPage().

The refactored code is rebased on current main (v0.17.1, commit c9691c6), all 333 existing tests pass, zero type errors.

I've opened a new PR with the BrowserContext-based approach: #991

Happy to also add it behind a flag as @matthiasrohmer suggested if that's preferred.

[OrKoN]

If the browser contexts satisfy the requirements, we do not need create_session, list_sessions, close_session tools. Instead, the new page tool should accept an optional browserContext: string parameter, if specified the MCP context should create a new browser context and create a page in it. MCPContext should maintain the mapping between the LLM-provided browserContext name and the actual browser context. If a browser context found that does not exist in the mapping, an automatic name should be generated (e.g., browser-context-1). When a page list snapshot is captured, the pages from all mapped browser contexts should be included. In the row for each each, browserContext=${llmDefinedBrowserContextName} should be added.

[RobertWsp]

Update: I've reworked PR #991 to follow @OrKoN's simpler design — no dedicated session tools at all.

New API

The new_page tool now accepts an optional browserContext parameter:

new_page url="https://admin.example.com" browserContext="admin"
new_page url="https://app.example.com" browserContext="user"

Page list output shows the context for each page:

Page 1: [admin.example.com] (browserContext=admin)
Page 2: [app.example.com] (browserContext=user)

How it works

• McpContext maintains a Map<string, BrowserContext> mapping names → Puppeteer BrowserContexts
• Pages in different contexts have fully isolated cookies, localStorage, IndexedDB, and WebSocket connections
• Unknown contexts discovered at runtime get auto-named (browser-context-1, browser-context-2, etc.)
• Closing the last page in a context automatically cleans it up

Addressing previous concerns

@natorion @matthiasrohmer — re: the concern about models over-eagerly creating sessions — since there are no session tools at all, the LLM only creates a browser context when it explicitly needs isolation (via the browserContext parameter on new_page). Default behavior is unchanged.

For real-time testing (e.g., WebSocket chat), the pattern is straightforward:

1. new_page url="https://app.com/chat" browserContext="userA"
2. new_page url="https://app.com/chat" browserContext="userB"
3. select_page pageId=1 → send message as userA
4. select_page pageId=2 → verify message received by userB

PR: #991