{"slug": "browsermesh-isolated-playwright-sessions-for-mcp-clients", "title": "BrowserMesh – isolated Playwright sessions for MCP clients", "summary": "BrowserMesh, an open-source local browser runtime for external AI clients, lets MCP-compatible tools such as Claude Code, Codex, Cursor, and Qwen control multiple isolated Chromium sessions via explicit sessionId and pageId addressing, with each session running in its own BrowserContext to prevent state sharing. Version 0.1, targeting Node.js 22+, includes features like semantic locators, per-session serialization, and parallel execution, and is designed to be configured once and driven by the AI client, not manually operated.", "body_md": "BrowserMesh is a local, open-source browser runtime for external AI clients.\n\nIt lets Claude Code, Codex, Cursor, Qwen, and other MCP-compatible clients control multiple isolated browser sessions through one MCP server.\n\nBrowserMesh replaces an implicit \"current page\" model with explicit `sessionId`\n\n+ `pageId`\n\naddressing.\n\nEach session runs in its own Chromium `BrowserContext`\n\n, so independent users, accounts, roles, and authentication states do not accidentally share cookies, storage, pages, or browser state.\n\n```\nUser\n  ↓\nExternal AI client\n  ↓ MCP\nBrowserMesh\n  ├── Session buyer  → isolated BrowserContext\n  ├── Session seller → isolated BrowserContext\n  └── Session admin  → isolated BrowserContext\n```\n\nBrowserMesh does not perform LLM reasoning.\n\nThe external MCP client decides what to do. BrowserMesh provides deterministic browser capabilities.\n\nA normal user configures BrowserMesh once and then asks their AI client things like:\n\nTest the checkout flow as a customer while simultaneously verifying the order from the admin account.\n\nThe AI client can discover BrowserMesh tools through MCP, create separate sessions for the required identities, operate them independently, and report the result.\n\nBrowserMesh is not:\n\n- an internal AI-agent framework;\n- an LLM orchestrator;\n- a message bus;\n- a Playwright fork;\n- a browser GUI;\n- an interactive shell that users must operate manually.\n\nVersion 0.1 is intentionally small:\n\n```\none Node.js process\n        │\n        ▼\none Chromium process\n        │\n        ├── BrowserContext A\n        ├── BrowserContext B\n        ├── BrowserContext C\n        └── ...\n```\n\nBrowserMesh v0.1 includes:\n\n- explicit session/page addressing;\n- isolated Chromium contexts;\n- session/page lifecycle;\n- browser navigation and interaction;\n- semantic locators;\n- per-session operation serialization;\n- parallel execution across independent sessions;\n- bounded operation timeouts;\n- structured application errors;\n- Playwright storage-state persistence;\n- MCP stdio integration;\n- deterministic local integration/e2e testing;\n- graceful shutdown and resource cleanup.\n\nReasoning and workflow orchestration remain in the external MCP client.\n\nYou normally do **not** call BrowserMesh tools manually.\n\nThe intended flow is:\n\n- Configure BrowserMesh once in your MCP-compatible AI client.\n- The client starts BrowserMesh as an MCP stdio process.\n- The client discovers BrowserMesh tools.\n- You describe the browser task in natural language.\n- The AI client chooses and invokes the appropriate BrowserMesh tools.\n- BrowserMesh executes the browser operations and returns structured results.\n\nFor tasks involving multiple users, accounts, roles, or authentication states, the external AI client should create a separate BrowserMesh session for each identity.\n\nOnce the npm package is published, the expected MCP configuration will use the package executable directly.\n\nInstall the Playwright-managed Chromium build once before starting BrowserMesh. This command uses the exact Playwright version bundled with the selected BrowserMesh package:\n\n```\nnpx -y multi-agent-browser-mcp --install-browser\n```\n\nPlaywright browser binaries are versioned separately from the npm package and may need to be\ninstalled again after a BrowserMesh/Playwright update. If Chromium is missing, BrowserMesh keeps\nMCP discovery available and `browser_session_create`\n\nreturns an actionable `BROWSER_ERROR`\n\ninstead\nof terminating the stdio connection.\n\nExample:\n\n```\n{\n  \"mcpServers\": {\n    \"browsermesh\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"multi-agent-browser-mcp\"]\n    }\n  }\n}\n```\n\nThe exact configuration format depends on the MCP client.\n\nBrowserMesh itself remains local: Chromium and BrowserMesh run on the user's machine.\n\nNo BrowserMesh cloud server is required for the open-source local mode.\n\nBrowserMesh v0.1 targets Node.js 24 and supports Node.js 22 as its minimum supported major version.\n\nClone the repository and run:\n\n```\nnpm install\nnpx playwright install chromium\nnpm run build\n```\n\nThen configure an MCP client to launch the locally built server:\n\n```\n{\n  \"mcpServers\": {\n    \"browsermesh\": {\n      \"command\": \"node\",\n      \"args\": [\"/absolute/path/to/browsermesh/dist/cli.js\"]\n    }\n  }\n}\n```\n\nFor development:\n\n```\nnpm run verify\nnpm run verify:package\n```\n\nThere is no global:\n\n- current session;\n- active session;\n- current page;\n- active page;\n- current tab.\n\nEvery browser operation explicitly identifies its session.\n\nEvery page-specific operation explicitly identifies its page.\n\nConceptually:\n\n```\nbrowser_session_create\n        │\n        ▼\n{\n  sessionId,\n  pageId\n}\n        │\n        ▼\nbrowser_navigate({\n  sessionId,\n  pageId,\n  ...\n})\n```\n\nA newly created session contains one deterministic initial page.\n\n`browser_session_create`\n\nreturns the initial `pageId`\n\nimmediately so an AI client does not need an additional `browser_page_list`\n\ncall before its first browser action.\n\nThe page also appears in `browser_page_list`\n\nand is marked `isDefault`\n\n.\n\nSession views consistently expose `sessionId`\n\n; page views consistently expose `pageId`\n\nand their owning `sessionId`\n\n.\n\nThe `isDefault`\n\nmarker is informational only. Browser operations still use explicit `pageId`\n\naddressing.\n\nEach ready BrowserMesh session maps to its own non-persistent Chromium `BrowserContext`\n\n.\n\nTherefore independent sessions must not accidentally share:\n\n- cookies;\n- browser storage/authentication state;\n- pages;\n- page references;\n- current URLs;\n- DOM snapshots;\n- screenshots;\n- form state.\n\nA `pageId`\n\nbelonging to one session cannot be used through another session.\n\nCross-session page addressing is rejected.\n\nEvery live session has an independent serial operation queue.\n\nOperations targeting the same session execute deterministically in accepted order.\n\nFor example:\n\n```\nSession A\n\nnavigate\n   ↓\nsnapshot\n   ↓\nclick\n   ↓\nget_url\n```\n\nA read-style operation does not bypass an in-progress navigation or interaction.\n\nA failed or timed-out operation must not poison the queue. Later accepted operations continue normally after the failed operation settles.\n\nDifferent sessions do **not** share a global operation lock:\n\n```\nSession A ═════════════════════►\n\nSession B ═════════════════════►\n\nSession C ═════════════════════►\n```\n\nThis allows independent browser workflows to run concurrently.\n\nWhen session close begins:\n\n- the session enters\n`closing`\n\n; - new operations targeting it are rejected;\n- operations already accepted into its queue are drained;\n- its pages and\n`BrowserContext`\n\nare closed; - live engine handles are removed;\n- the session becomes closed.\n\nRepeated close of a known closing/closed session is safe and returns an idempotent success result.\n\nA completely unknown session ID still returns `SESSION_NOT_FOUND`\n\n.\n\n`browser_session_create`\n\n`browser_session_list`\n\n`browser_session_get`\n\n`browser_session_close`\n\n`browser_page_create`\n\n`browser_page_list`\n\n`browser_page_close`\n\n`browser_navigate`\n\n`browser_back`\n\n`browser_forward`\n\n`browser_reload`\n\n`browser_get_url`\n\n`browser_get_title`\n\n`browser_snapshot`\n\n`browser_visible_text`\n\n`browser_click`\n\n`browser_fill`\n\n`browser_press`\n\n`browser_select_option`\n\n`browser_screenshot`\n\nScreenshots are returned as MCP image content instead of being written to a caller-controlled filesystem path.\n\n`browser_state_save`\n\n`browser_state_list`\n\n`browser_state_remove`\n\n`browser_session_create`\n\naccepts an optional `stateId`\n\n.\n\nWithout `stateId`\n\n, it creates a fresh isolated context.\n\nWith `stateId`\n\n, it initializes the new context using a previously saved BrowserMesh state.\n\nExample conceptually:\n\n```\nbrowser_session_create({\n  name: \"buyer\",\n  stateId: \"buyer-auth\"\n})\n```\n\nA session may have:\n\n- an optional human-readable\n`name`\n\n; - optional string metadata.\n\nFor example an external AI client may label sessions:\n\n```\nrole=buyer\nrole=seller\naccount=work\n```\n\nThese values are neutral workflow labels only.\n\nThey do **not** create:\n\n- internal Agent entities;\n- ownership principals;\n- permissions;\n- mailboxes;\n- message channels;\n- LLM identities.\n\nBrowserMesh tool descriptions are part of the product contract.\n\nDescriptions must explain both what a tool does and when an AI client should use it.\n\nFor example, the description for `browser_session_create`\n\nmust make it clear that separate sessions should be used for:\n\n- different users;\n- different accounts;\n- different roles;\n- different authentication states;\n- independent parallel browser workflows.\n\nThe goal is that a user can say:\n\nTest this application as a buyer and an administrator.\n\nwithout having to manually instruct the AI to call `browser_session_create`\n\ntwice.\n\nBrowser actions prefer semantic locator strategies.\n\nSupported v0.1 strategies include:\n\n- role;\n- text;\n- label;\n- placeholder;\n- test ID;\n- CSS as an escape hatch.\n\nCommon interactive role values are supported by the v0.1 public contract.\n\nRole names use exact accessible-name matching by default. Set `exact: false`\n\nonly when partial\nmatching is intentional. If a locator resolves to multiple elements, BrowserMesh returns\n`LOCATOR_AMBIGUOUS`\n\nand keeps the session usable.\n\nAccessibility snapshots redact non-empty values from `input[type=\"password\"]`\n\nelements before any\nsnapshot content crosses the MCP boundary.\n\nBrowserMesh does not expose Playwright `Locator`\n\nobjects through its public API.\n\nBrowserMesh stores local persistence data beneath:\n\n```\n.browsermesh/\n```\n\nby default.\n\nSaved browser state may contain authentication credentials or equivalent sensitive browser state.\n\nTherefore:\n\n`.browsermesh/`\n\nis ignored by Git;- saved state must not be committed;\n- saved state must not be published;\n- logs must not contain storage-state contents;\n- callers provide logical state IDs, not arbitrary filesystem paths.\n\nPersistence represents serialized browser storage/auth state.\n\nBrowserMesh never attempts to serialize a live `BrowserContext`\n\n, open pages, pending operations, or live browser process state.\n\n| Environment variable | Default | Meaning |\n|---|---|---|\n`BROWSERMESH_TIMEOUT_MS` |\n`10000` |\nDefault bounded operation timeout |\n`BROWSERMESH_DATA_DIR` |\n`.browsermesh` |\nPrivate local data directory |\n`BROWSERMESH_LOG_LEVEL` |\n`info` |\n`debug` , `info` , `warn` , `error` , or `silent` |\n`BROWSERMESH_MAX_SESSIONS` |\n`50` |\nActive session limit |\n`BROWSERMESH_MAX_PAGES` |\n`20` |\nManaged pages per session |\n`BROWSERMESH_PERSISTENCE` |\n`true` |\nEnable saved browser state |\n\nConfiguration is read and validated centrally.\n\nThe BrowserMesh CLI always launches Chromium in headed mode when the first browser session is\ncreated so the user can observe browser automation. Browser startup is lazy so MCP discovery and\nactionable setup errors remain available when Chromium has not been installed yet. Set a larger\nper-tool `timeoutMs`\n\nonly for operations that are expected to take longer than the safe default.\n\nDirect scattered `process.env`\n\naccess throughout the codebase is not allowed.\n\nMCP stdio reserves stdout for protocol traffic.\n\nBrowserMesh structured logs therefore go to stderr.\n\nLogs may contain safe correlation information such as:\n\n`operationId`\n\n;`sessionId`\n\n;`pageId`\n\n;- tool/operation name;\n- duration;\n- safe error code.\n\nLogs must not contain:\n\n- cookies;\n- tokens;\n- saved state;\n- page contents;\n- screenshots;\n- form values;\n- passwords;\n- arbitrary message payloads.\n\nBrowserMesh does not silently reconstruct live sessions if Chromium unexpectedly disconnects.\n\nAffected sessions transition to a failed state and their live handles are invalidated.\n\nExisting sessions are never silently recreated because doing so would violate BrowserMesh state guarantees.\n\nA fresh Chromium process may be started for future newly created sessions if the runtime can safely recover, but old live sessions remain failed.\n\n```\nnpm run typecheck\nnpm run lint\nnpm run format:check\nnpm test\nnpm run test:integration\nnpm run test:e2e\nnpm run test:stress\nnpm run test:coverage\nnpm run build\nnpm run verify\n```\n\nBrowser integration/e2e tests use real Chromium together with a deterministic loopback HTTP test server.\n\nTests do not depend on public websites.\n\nSee:\n\n[Technical specification](/scrollDynasty/multi-agent-browser-mcp/blob/master/docs/SPEC.md)[Architecture](/scrollDynasty/multi-agent-browser-mcp/blob/master/docs/architecture.md)[Development](/scrollDynasty/multi-agent-browser-mcp/blob/master/docs/development.md)[Contributing](/scrollDynasty/multi-agent-browser-mcp/blob/master/CONTRIBUTING.md)[Release process](/scrollDynasty/multi-agent-browser-mcp/blob/master/docs/releasing.md)[Security policy](/scrollDynasty/multi-agent-browser-mcp/blob/master/SECURITY.md)[Architecture decisions](/scrollDynasty/multi-agent-browser-mcp/blob/master/docs/decisions)\n\nPull request titles follow Conventional Commits. Every PR is checked by the full test matrix, package-install smoke tests, semantic-title validation, and CodeQL. Releases are prepared by Release Please and published to npm through GitHub OIDC only after a maintainer merges the generated Release PR.\n\nBrowserMesh is distributed under the [Apache License 2.0](/scrollDynasty/multi-agent-browser-mcp/blob/master/LICENSE).\n\nBrowserMesh v0.1 intentionally does not include:\n\n- Firefox/WebKit parity;\n- remote Streamable HTTP;\n- BrowserMesh-hosted cloud infrastructure;\n- multi-tenant authentication;\n- distributed browser workers;\n- live-operation crash recovery;\n- internal Agent entities;\n- internal session ownership tied to LLM agents;\n- Agent registries;\n- mailboxes;\n- agent-to-agent messaging;\n- internal LLM calls;\n- prompt orchestration;\n- Claude/Codex/Qwen process spawning;\n- arbitrary shell execution;\n- arbitrary filesystem reads;\n- caller-controlled screenshot paths;\n- downloads;\n- web dashboard;\n- network allowlist;\n- full Playwright API.\n\nA future generic client/workflow lease may be introduced if real multi-client protection requires it.\n\nSuch a lease must remain independent of LLM/Agent abstractions.\n\nWithin one BrowserMesh runtime:\n\n- sessions are explicitly addressed;\n- pages are explicitly addressed;\n- each session has an isolated browser context;\n- different sessions may execute concurrently;\n- operations targeting one session execute deterministically through that session's queue;\n- failures do not poison future queued operations;\n- persisted state is handled through controlled logical identifiers;\n- shutdown cleans up live browser resources;\n- BrowserMesh performs browser execution while reasoning remains outside the runtime.", "url": "https://wpnews.pro/news/browsermesh-isolated-playwright-sessions-for-mcp-clients", "canonical_source": "https://github.com/scrollDynasty/multi-agent-browser-mcp", "published_at": "2026-08-13 04:38:04+00:00", "updated_at": "2026-08-13 04:40:35.114405+00:00", "lang": "en", "topics": ["developer-tools", "ai-tools", "ai-infrastructure"], "entities": ["BrowserMesh", "Claude Code", "Codex", "Cursor", "Qwen", "Playwright", "Chromium", "MCP"], "alternates": {"html": "https://wpnews.pro/news/browsermesh-isolated-playwright-sessions-for-mcp-clients", "markdown": "https://wpnews.pro/news/browsermesh-isolated-playwright-sessions-for-mcp-clients.md", "text": "https://wpnews.pro/news/browsermesh-isolated-playwright-sessions-for-mcp-clients.txt", "jsonld": "https://wpnews.pro/news/browsermesh-isolated-playwright-sessions-for-mcp-clients.jsonld"}}