Support isolatedContext page-scoped tool routing for multi-agent workflows

[passtas]

Problem

PR #991 adds isolatedContext to new_page, enabling agents to create pages with isolated cookies, storage, and sessions. However, all subsequent tools (take_screenshot, take_snapshot, navigate_page, evaluate_script, emulate, click, fill, press_key, etc.) resolve their target page via the global getSelectedPage(). This means agents must call select_page before each operation, which introduces a race condition in multi-agent workflows.

The internal mutex serializes individual tool calls, but it doesn't prevent interleaving between two sequential calls from the same agent:

Step	Mutex processes	#selectedPage after	Correct?
1	Agent A: select_page(2)	Page 2	Yes
2	Agent B: select_page(3)	Page 3	Yes
3	Agent A: take_screenshot()	Page 3 (captures wrong page)	No, wanted Page 2

Each call is atomic, but Agent A has no way to hold the mutex across both calls. Agent B's select_page mutates the shared #selectedPage state in between.

Use cases

(genuinely using it like that)

Parallel site exploration for specification writing. A team of agents explores a large e-commerce site to produce functional specifications for each domain (navigation, product listing, product detail, checkout, account, etc.). A single agent doing this sequentially takes hours. With 3-5 parallel agents, each assigned a domain and operating in its own isolated context, the same work completes in a fraction of the time. Each agent needs to navigate, take snapshots, fill forms, and interact with elements independently.

Cross-session cache and state testing. Two agents investigate caching issues by browsing the same site simultaneously: one logged in as a premium user, the other as a guest. Isolated contexts give them separate cookies and sessions, but they need to take screenshots, evaluate scripts, and compare DOM state in parallel to catch bugs where one user sees another's cached data.

Responsive design auditing. Multiple agents emulate different viewports (mobile, tablet, desktop) on the same site in parallel. Each agent operates in its own isolated context with a different viewport configuration, taking screenshots and snapshots across the same set of pages to compare layout differences.

Multi-locale testing. Agents browse separate locale-specific versions of a site (en-US, de-DE, ja-JP) in parallel, each in its own isolated context with different language/geo settings, verifying that translations, currency formatting, and regional content are correct.

Why separate MCP server instances don't solve this

Agent frameworks like Claude Code configure the MCP server once (in .mcp.json), and the framework launches a single server process. When the user spawns a team of parallel agents (for site exploration, cross-role testing, parallel crawling, etc.), all agents share that single MCP server. The user has no mechanism to give each agent its own server instance.

Proposed solution

Initially I proposed routing tools via the isolatedContext name from new_page. After discussion with @OrKoN, pageId routing is a better fit: it works for same-context multi-page scenarios, doesn't require isolated contexts, and the concept already exists in list_pages/select_page.

Add an optional pageId parameter to all page-operating tools. When provided, the tool resolves the target page directly, bypassing getSelectedPage(). When omitted, behavior is unchanged.

// Single-agent (unchanged):
take_screenshot()

// Multi-agent (atomic, no select_page needed):
take_screenshot(pageId: 2)

Agents get the page ID from the new_page / list_pages response and pass it to every subsequent call. No new concepts to track, and select_page is no longer needed in multi-agent flows.

Implementation

PR at #1022 (feat/isolated-context-page-routing branch).

[OrKoN]

I do not think this is specifically related to isolated contexts, I imagine multi-agent setups might need to workin in parallel on the same user context sometimes.

It also eliminates the need for select_page in multi-agent flows, which actually saves tokens compared to the current select_page + tool pattern.

how would it work with multiple pages in the isolated context? what if multiple agents still operate on the same isolated context? Note that the token count will be increased for all clients because the optional parameter (most likely optional pageId or the proposed isolated context) definition repeated in all tools would need to be included into llm context.

Also, select_page does some focus emulation and dialog handling that need to be applied to all pages. cc @natorion

[OrKoN]

@passtas is there a way to configure claude to start a new MCP server session for each sub-agent?

[OrKoN]

@natorion tldr; basically with multi-agent workflows each subagent does not know which commands were previously sent to the MCP server session and they can change the MCP server state independently resulting in unexpected outcomes. I do not see any other way to solve it other then allowing optional pageId on each of the tool calls to allow tool calls to act independently. WDYT?

[OrKoN]

@passtas do you know if for the MCP servers with the HTTP transport Claude would create multiple MCP session in the multi-agent setup?

[passtas]

I do not think this is specifically related to isolated contexts, I imagine multi-agent setups might need to workin in parallel on the same user context sometimes.

It also eliminates the need for select_page in multi-agent flows, which actually saves tokens compared to the current select_page + tool pattern.

how would it work with multiple pages in the isolated context? what if multiple agents still operate on the same isolated context? Note that the token count will be increased for all clients because the optional parameter (most likely optional pageId or the proposed isolated context) definition repeated in all tools would need to be included into llm context.

Also, select_page does some focus emulation and dialog handling that need to be applied to all pages. cc @natorion

Yep, I think you are right that passing pageId is arguably better solution, especially if there is focus emulation and it is the real requirement is just "tell the tool which page to act on" regardless of context boundaries. It works for same-context multi-page scenarios, doesn't require isolated contexts, and the same agent can operate on any page it knows the ID of. I was just trying to balance what is already implemented.

On token overhead - both isolatedContext and pageId add one optional parameter definition per tool. In single-agent flows the parameter is never passed, but the definition is still in the schema. That cost seems unavoidable.

@passtas is there a way to configure claude to start a new MCP server session for each sub-agent?

I see where you are going with this :). But no - Claude Code configures MCP servers in .mcp.json at the project level. The framework launches one server process and all sub-agents share it. There's no config mechanism to give each sub-agent its own instance.

Although it may not be bad idea for them to incorporate, I think it is easier for subagents/teammates to not worry about the mcp config and assume everything is spined up for them already.

[passtas]

@passtas do you know if for the MCP servers with the HTTP transport Claude would create multiple MCP session in the multi-agent setup?

Based on "short" research with Mr. Claude:

To investigate specifically the agent teams I looked into the Claude Code runtime (v2.1.50, bundled cli.js).

All agents share the same MCP server connections, regardless of transport type. There's no per-agent session isolation at any level:

• Task tool agents (foreground sub-agents) receive the parent's toolUseContext directly, which includes mcp.clients. No new connections are established.
• In-process teammates (via TeamCreate) also receive the parent's toolUseContext by reference. AsyncLocalStorage only marks isInProcess: true but does not isolate MCP state.
• There is no separate-process teammate backend. Tmux/split-pane display mode is purely visual; all teammates run as async tasks within the same Node.js process.

MCP server processes are started once at application startup. StdioClientTransport children or SSEClientTransport connections are stored in shared AppState.mcp.clients and never duplicated when agents are spawned.

So:

• A new MCP server session per sub-agent is not possible today.
• HTTP transport would not help either: the same SSEClientTransport instance is shared across all agents. No new Initialize handshake or Mcp-Session-Id is created per agent.

This is a relatively heavily requested feature on the Claude Code side (anthropics/claude-code#4476, anthropics/claude-code#6915) but not implemented.

Note: Claude Code is not open source (the anthropics/claude-code repo is just the public issue tracker and plugins). The analysis above was done by reading the minified bundled source in the npm package.

[OrKoN]

On token overhead - both isolatedContext and pageId add one optional parameter definition per tool. In single-agent flows the parameter is never passed, but the definition is still in the schema. That cost seems unavoidable.

I think one option would be to add pageId args behind a CLI flag.

[mathiasbynens]

@natorion WDYT?

[passtas]

On token overhead - both isolatedContext and pageId add one optional parameter definition per tool. In single-agent flows the parameter is never passed, but the definition is still in the schema. That cost seems unavoidable.

I think one option would be to add pageId args behind a CLI flag.

Would that be practical? The tool description still will have an increased size, or you want it for some other reason?

[OrKoN]

the tool pageId argument would be only added to descriptions if the CLI arg is set. This way it can be turned on for multi-agent setups. But let us align on this feature internally first. We would go from ~6916 to ~7267 adding the pageId to each tool which does not look too bad.