Provides an isolated multi-session Chromium runtime that allows AI clients to run multiple independent browser sessions in parallel.
Also known as scrollDynasty/multi-agent-browser-mcp, multi-agent-browser-mcp
- Stars
- 3
- Tools
- 35
- Downloads, 30 days
- —
- Latest version
- 0.2.1
- Last commit
- Nov 13, 2026
- License
- Apache-2.0
What is BrowserMesh MCP?
BrowserMesh provides an isolated multi-session Chromium runtime that allows AI clients to run multiple independent browser sessions in parallel. It exposes 35 tools, such as browser_runtime_info, browser_session_create, browser_session_list.
Summary generated from the project's README
About BrowserMesh MCP server
BrowserMesh provides a local Chromium runtime designed for AI clients that need to manage multiple independent browser sessions simultaneously. Unlike standard browser MCP servers that typically control a single tab, this server allows for parallel execution across many isolated contexts. Each session maintains its own unique cookies, storage, and authentication state, ensuring that actions in one window do not interfere with another.
Developers can use this server with MCP-compatible clients such as Claude Desktop, Claude Code, Cursor, Windsurf, and Qwen. It operates via MCP stdio and runs entirely on your local machine rather than a hosted cloud service. The system uses explicit session and page addressing through tools like browser_session_create and browser_navigate to ensure deterministic control over specific browser instances. This makes it ideal for complex workflows requiring different user roles or accounts to be active at the same time.
What you can do with it
- 1Simultaneous multi-role testingAn AI can test a checkout process as a customer while simultaneously verifying the order from an administrator account.
Written from the project's README. Every use case is checked against a quote from it.
How to install BrowserMesh MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall BrowserMesh MCP in Claude Code
$ claude mcp add multi-agent-browser-mcp -- npx -y browsermeshInstall BrowserMesh MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"multi-agent-browser-mcp": {
"command": "npx",
"args": [
"-y",
"browsermesh"
]
}
}
}Install BrowserMesh MCP in VS Code
.vscode/mcp.json
{
"servers": {
"multi-agent-browser-mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"browsermesh"
]
}
}
}Install BrowserMesh MCP in VS Code CLI
$ code --add-mcp '{"name":"multi-agent-browser-mcp","type":"stdio","command":"npx","args":["-y","browsermesh"]}'Install BrowserMesh MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"multi-agent-browser-mcp": {
"command": "npx",
"args": [
"-y",
"browsermesh"
]
}
}
}Install BrowserMesh MCP in Codex
$ codex mcp add multi-agent-browser-mcp -- npx -y browsermeshInstall BrowserMesh MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.multi-agent-browser-mcp] command = "npx" args = ["-y", "browsermesh"]
Install BrowserMesh MCP in Gemini CLI
$ gemini mcp add -s user multi-agent-browser-mcp npx -- -y browsermeshInstall BrowserMesh MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"multi-agent-browser-mcp": {
"command": "npx",
"args": [
"-y",
"browsermesh"
]
}
}
}Started by HostedMCP on 16 Nov 2026
We ran this command for browsermesh 0.2.1 in an isolated container with no network and no keys. It answered and listed 35 tools.
BrowserMesh MCP tools 35
Read from the server with tools/listbrowser_runtime_infoRead-onlyReport bounded, read-only BrowserMesh version, launch state, effective configuration, and session counts without launching Chromium. Use this to diagnose setup and capacity safely; it never returns paths, launch arguments, environment values, browser state, or raw errors.
browser_session_createActionCreate a new isolated browser session with its own cookies, storage, pages, and optional validated contextSettings (viewport, scale, locale, timezone, color scheme, reduced motion, user agent, geolocation, and explicit origin-scoped geolocation grants). Only the geolocation permission is supported; each grant must name one absolute HTTP(S) origin, never a wildcard. Create a separate session whenever a task involves a different user, account, role, authentication state, device profile, accessibility preference, permission profile, or independent parallel workflow; never reuse one session for identities or context settings that must remain isolated. The response directly returns both sessionId and the deterministic initial pageId plus normalized effective settings. Pass stateId only to restore previously saved browser state.
browser_session_listRead-onlyList every browser session with its explicit sessionId, lifecycle status, name, and neutral workflow metadata. Use this to recover the correct session for each role/account; there is no global active session.
browser_session_getRead-onlyInspect one explicitly addressed browser session. Session names and metadata are workflow labels, not internal AI agents or owners.
browser_session_closeActionClose one explicitly addressed session and release all of its pages and isolated browser context. Close each role/account session when its workflow is complete.
browser_page_createActionCreate an additional page inside one explicitly addressed session. Use it for another tab that must share that session's cookies and storage; use a separate session instead when identity or authentication must be isolated.
browser_page_listRead-onlyList pages belonging only to the addressed session. Session creation already returns the initial pageId; use this tool to rediscover or inspect all pages in that session.
browser_page_closeActionClose one explicitly addressed page in its owning session. Supply both IDs because BrowserMesh has no global current session or page.
browser_navigateActionNavigate one explicitly addressed page to an absolute HTTP(S) URL. Keep using the sessionId/pageId pair for the intended account or role; navigation never changes a global active page.
browser_backActionNavigate backward in the history of one explicitly addressed page without affecting pages or sessions used by other roles.
browser_forwardActionNavigate forward in the history of one explicitly addressed page without affecting other isolated sessions.
browser_reloadActionReload one explicitly addressed page in its existing isolated session and authentication state.
Show all 35 toolsShow fewer tools
browser_get_urlRead-onlyRead the current URL of one explicitly addressed page. Use the IDs returned for the intended session; there is no global current page.
browser_get_titleRead-onlyRead the title of one explicitly addressed page in its owning isolated session.
browser_snapshotRead-onlyInspect a bounded accessibility-oriented snapshot of one explicitly addressed page, optionally scoped by a locator including a bounded semantic iframe chain. BrowserMesh rejects oversized DOM sources before native ARIA serialization. Use interactiveOnly to retain interactive nodes with ancestor context and maxChildren to limit every node after filtering. A nextCursor continues the immutable captured serialization without rereading a changed DOM; cursors are page-scoped, expire after 30 seconds, and become stale on navigation or close. Semantic scope, depth, boxes, character/byte bounds, omissions, and truncation are explicit; partial content is aria-yaml-fragment. Non-empty password-input values are redacted before content crosses MCP. Optional 30-second element refs are separate short-lived action conveniences.
browser_visible_textRead-onlyRead visible text from a semantic or CSS locator on one explicitly addressed page. A locator may select the top document or a bounded outer-to-inner semantic iframe chain; the lookup remains confined to that page and session.
browser_observeRead-onlyRead bounded observations recorded for one explicitly addressed page. Choose source: 'console' for console events, 'pageError' for uncaught page errors, 'network' for correlated request/response metadata, or 'requestFailed' for transport-level failures. HTTP error responses such as 500 are 'network' response events, not 'requestFailed'. Console and page-error results are metadata-only unless includeText=true, which the network sources reject because they carry no text; exposed text is best-effort redacted and bounded, and console argument objects and raw stacks are never captured. Network URLs remove credentials and fragments and redact sensitive query values; headers, cookies, bodies, storage, WebSockets, service-worker traffic, data URLs, and blob URLs are never captured. Use sinceEventId as a non-destructive checkpoint and inspect gap and droppedCount before treating the evidence as complete.
browser_clickActionClick exactly one semantic/CSS locator or short-lived snapshot ref on one explicitly addressed page. A locator may select the top document or a bounded outer-to-inner semantic iframe chain. Role locator names match exactly by default and every iframe-chain selector must resolve exactly; ambiguous locators return LOCATOR_AMBIGUOUS and stale or cross-page refs return STALE_ELEMENT_REFERENCE. Prefer semantic locators for durable workflows.
browser_double_clickActionDouble-click a semantic or CSS locator on one explicitly addressed page. Use this only when the application assigns distinct double-click behavior; the action is serialized with all browser work in that session and an ambiguous locator returns LOCATOR_AMBIGUOUS.
browser_hoverActionMove the pointer over a semantic or CSS locator on one explicitly addressed page. Use this to reveal hover-driven controls or state before inspecting or interacting; BrowserMesh preserves same-session accepted order.
browser_focusActionFocus a semantic or CSS locator on one explicitly addressed page without entering a value. Use this for focus-driven UI state or before a separate key action; the locator remains scoped to the supplied sessionId and pageId.
browser_checkActionEnsure a checkbox or radio located semantically or by CSS is checked on one explicitly addressed page. The operation is idempotent, bounded by timeoutMs, and isolated to the supplied session.
browser_uncheckActionEnsure a checkbox located semantically or by CSS is unchecked on one explicitly addressed page. The operation is idempotent, bounded by timeoutMs, and isolated to the supplied session.
browser_scroll_into_viewActionScroll one semantic or CSS locator into the viewport of an explicitly addressed page. Use this before inspection or interaction when an off-screen target must become visible; it never accepts arbitrary JavaScript or coordinates.
browser_scrollActionScroll an explicitly addressed page by bounded integer pixel deltas. Use deltaX for horizontal and deltaY for vertical movement; this typed operation exposes no arbitrary JavaScript and remains serialized within the session.
browser_drag_and_dropActionDrag one semantic or CSS-located element onto another on one explicitly addressed page. Source and target are resolved in the same page and session, with bounded timeout and strict ambiguity errors.
browser_fillActionFill a form field located on one explicitly addressed page. The value is entered only in that session; use separate sessions for different identities.
browser_pressActionPress a key on a locator within one explicitly addressed page, preserving deterministic ordering with other operations in that session. A missing or unsuitable element returns OPERATION_TIMEOUT within timeoutMs (10 seconds by default) without closing MCP or browser sessions.
browser_select_optionActionSelect an option on one explicitly addressed page using a semantic or CSS locator. A missing or unsuitable select returns OPERATION_TIMEOUT within timeoutMs (10 seconds by default), and the supplied session plus all other sessions remain usable.
browser_screenshotRead-onlyCapture a bounded in-memory PNG screenshot of one explicitly addressed page, either as the viewport/full page or one semantic element optionally reached through a bounded iframe chain. Full-page and element capture use an immutable measured CSS-pixel clip plus encoded-byte validation. BrowserMesh returns image content and does not write to a caller-controlled path or inspect another session.
browser_waitRead-onlyWait for one deterministic passive condition on an explicitly addressed page: an exact/safe-glob URL, domcontentloaded/load state, locator state (optionally through a bounded semantic iframe chain), or case-sensitive top-document text presence/absence. The wait occupies that session queue, is bounded by timeoutMs, and must not depend on a later action queued in the same session; use browser_action_and_wait for action-triggered events.
browser_action_and_waitActionAtomically register a navigation, response, popup, or dialog waiter first, then click or press on the explicitly addressed page under one shared deadline; the action locator may use a bounded semantic iframe chain. Popup pages receive a new BrowserMesh pageId in the same session with isDefault=false and are closed if the page limit is exceeded. Dialogs must be handled atomically because they cannot be inspected later; specify the expected type and accept/dismiss action. Returned dialog text is bounded. Use this instead of parallel same-session calls when an action triggers the event.
browser_state_saveActionSave cookies and supported storage from one explicitly addressed session under a safe logical stateId. Use this only when a later new isolated session should restore that authentication state.
browser_state_listRead-onlyList logical saved-state IDs available for optional restoration when creating a new isolated session; state contents and secrets are not returned.
browser_state_removeActionDelete persisted browser state by its safe logical stateId when it should no longer be restorable. This does not close or alter currently live sessions.
Automated checks
Ran Nov 13, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablePass
- Open source license (OSI)Pass
- Commit or release in the last yearPass
- Package name not close to a popular packagePass
- Remote endpoint uses HTTPSNot checked
- Destructive tools are labelledPass
- No hidden instructions to the modelPass
- No critical advisory in the package or its dependenciesPass
README
View on GitHubBrowserMesh
Run many browser sessions at once, fully isolated from each other, from one MCP server.
Every other browser MCP server gives your AI client one browser with a current tab. BrowserMesh gives it as many independent sessions as the task needs — each with its own cookies, storage, and authentication — running in parallel. Test checkout as a customer while an admin session verifies the order, in one conversation, without either seeing the other's state.
External AI client
|
MCP stdio
|
BrowserMesh runtime
| | |
Session A Session B Session C
Context A Context B Context C
The external client reasons and plans. BrowserMesh executes browser operations, enforces isolation, orders work within each session, and returns structured results.
Works with Claude Code, Claude Desktop, Codex, Cursor, Windsurf, Qwen, and any other MCP-compatible client.
When to use BrowserMesh, and when not to
BrowserMesh is not a drop-in replacement for the general-purpose browser MCP servers. It is built around one thing those servers do not do, and it charges for it.
| You want to… | Reach for |
|---|---|
| Drive two or more accounts, roles, or auth states at the same time | BrowserMesh — a context per session, running in parallel |
| Keep a signed-in state and reuse it in a later, separate session | BrowserMesh — browser_state_save / stateId |
| Address a specific tab deterministically across a long workflow | BrowserMesh — explicit sessionId + pageId, no "current tab" |
| Bound what a page can spend of your context (snapshot size, refs, events) | BrowserMesh — every read is explicitly bounded and paginated |
| Browse, click, and read one page as one user | Playwright MCP — smaller surface, less to configure |
| Debug performance, tracing, or the CDP-level behaviour of a page | Chrome DevTools MCP — that is what it exposes |
| Run in someone else's cloud, with managed proxies and captcha handling | A hosted service such as Browserbase — BrowserMesh is local-only |
| Evaluate arbitrary JavaScript in the page | Playwright MCP or Chrome DevTools MCP — BrowserMesh has no such tool by design |
| Drive Firefox or WebKit | Playwright MCP — BrowserMesh is Chromium-only today |
The honest trade-off is discovery cost. BrowserMesh publishes 35 tools with full input and output
schemas; measured on one machine on one day, its tools/list is roughly 94 KB against 25 KB for
chrome-devtools-mcp and 18 KB for @playwright/mcp, both of which publish no output schemas. If
your client is short on context and your workflow is one browser and one user, that is a real
argument for a smaller server. Narrow the surface with --tools core when you do want BrowserMesh
but not all of it.
Quick start
Claude Code:
claude mcp add browsermesh -- npx -y browsermesh
Any other client, in its MCP configuration file:
{
"mcpServers": {
"browsermesh": {
"command": "npx",
"args": ["-y", "browsermesh"]
}
}
}
That is the whole setup. On its first start BrowserMesh downloads the Chromium build it uses, so
there is no separate install step. Pass --no-auto-install to manage the browser yourself, in
which case MCP discovery still works and browser_session_create returns an actionable
BROWSER_ERROR explaining what to run.
That first download happens before the server answers initialize, and a Chromium build is around
130 MB. Clients with a short connect timeout report the server as failed while it runs. On a slow
link, warm it once before adding the server and every later start is immediate:
npx -y browsermesh --install-browser
Then ask for the work in plain language:
Test the checkout flow as a buyer and confirm the order appeared, as an admin, at the same time.
The client creates one session per role on its own. BrowserMesh also publishes a parallel_roles
prompt that spells the workflow out, so a client can offer it directly.
Check an installation without starting the protocol:
npx -y browsermesh --doctor
Chromium and BrowserMesh remain on your machine. There is no hosted BrowserMesh service.
On connect, BrowserMesh sends your client a short instructions string. Alongside guidance on session
addressing and bug reporting, it asks your agent to check once whether you have starred the
repository — an authenticated GitHub call, made with your own gh credentials, for a purpose
unrelated to the browser task. Nothing is gated on it and declining changes nothing. Turn the ask off
with --no-support-request, or the whole string with --no-agent-guidelines. See
Built for agent-friendly workflows.
Renamed in 0.2. The npm package was
multi-agent-browser-mcpand is nowbrowsermesh, matching the name everything else already used. Changeargsto["-y", "browsermesh"]; nothing else moves.
v0.1 architecture
BrowserMesh v0.1 is intentionally small: one local Node.js process, one Chromium process, and one
non-persistent BrowserContext for every ready session.
It provides:
- explicit session and page addressing;
- isolated browser contexts and page ownership checks;
- navigation, inspection, interaction, waits, capture, and persistence;
- per-session serialization with parallel execution across independent sessions;
- bounded timeouts, structured errors, graceful shutdown, and resource cleanup;
- MCP stdio integration with deterministic integration and end-to-end tests.
BrowserMesh is a browser runtime, not an internal agent framework, LLM orchestrator, message bus, Playwright fork, browser GUI, or interactive shell.
How it is normally used
- Configure BrowserMesh once in an MCP-compatible AI client.
- The client starts BrowserMesh over stdio and discovers its tools.
- Describe the browser task in natural language.
- The client creates the required sessions and chooses the tools to invoke.
- BrowserMesh executes the operations and returns structured results.
Use a separate session for each user, account, role, authentication state, or independent parallel workflow. BrowserMesh tools are normally selected by the external client rather than called by hand.
Build from source
BrowserMesh v0.1 targets Node.js 24 and supports Node.js 22 as its minimum supported major version.
Clone the repository and run:
npm install
npx playwright install chromium
npm run build
Then configure an MCP client to launch the locally built server:
{
"mcpServers": {
"browsermesh": {
"command": "node",
"args": ["/absolute/path/to/browsermesh/dist/cli.js"]
}
}
}
For development:
npm run verify
npm run verify:package
Session model
There is no global:
- current session;
- active session;
- current page;
- active page;
- current tab.
Every browser operation explicitly identifies its session.
Every page-specific operation explicitly identifies its page.
Conceptually:
browser_session_create
│
▼
{
sessionId,
pageId
}
│
▼
browser_navigate({
sessionId,
pageId,
...
})
A newly created session contains one deterministic initial page.
browser_session_create returns the initial pageId immediately so an AI client does not need an additional browser_page_list call before its first browser action.
The page also appears in browser_page_list and is marked isDefault.
Session views consistently expose sessionId; page views consistently expose pageId and their owning sessionId.
The isDefault marker is informational only. Browser operations still use explicit pageId addressing.
Isolation
Each ready BrowserMesh session maps to its own non-persistent Chromium BrowserContext.
Therefore independent sessions must not accidentally share:
- cookies;
- browser storage/authentication state;
- pages;
- page references;
- current URLs;
- DOM snapshots;
- screenshots;
- form state.
A pageId belonging to one session cannot be used through another session.
Cross-session page addressing is rejected.
Concurrency model
Every live session has an independent serial operation queue.
Operations targeting the same session execute deterministically in accepted order.
For example:
Session A
navigate
↓
snapshot
↓
click
↓
get_url
A read-style operation does not bypass an in-progress navigation or interaction.
A failed or timed-out operation must not poison the queue. Later accepted operations continue normally after the failed operation settles.
Each timeoutMs is one absolute budget starting when BrowserMesh accepts the operation. Time spent
waiting in the owning session queue and every later browser-adapter step consume that same budget;
no adapter step receives a renewed full timeout.
MCP request cancellation is propagated into BrowserMesh as an engine-independent operation signal.
A same-session request cancelled while queued is skipped before it can touch browser state. If a
Playwright action is already running and cannot be aborted safely, BrowserMesh keeps its queue slot
until the real action settles, so later work cannot overtake it. Passive waits detach their owned
abort listeners and timers promptly, and the session queue remains usable after cancellation. MCP
clients observe their SDK's cancellation error (typically an AbortError, or an MCP error carrying
that reason); a separate tool result after protocol cancellation is not guaranteed.
Different sessions do not share a global operation lock:
Session A ═════════════════════►
Session B ═════════════════════►
Session C ═════════════════════►
This allows independent browser workflows to run concurrently.
Session closing
When session close begins:
- the session enters
closing; - new operations targeting it are rejected;
- operations already accepted into its queue are drained;
- its pages and
BrowserContextare closed; - live engine handles are removed;
- the session becomes closed.
Repeated close of a known closing/closed session is safe and returns an idempotent success result.
A completely unknown session ID still returns SESSION_NOT_FOUND.
Supported MCP tools
Sessions and pages
browser_runtime_infobrowser_session_createbrowser_session_listbrowser_session_getbrowser_session_closebrowser_page_createbrowser_page_listbrowser_page_close
Navigation
browser_navigatebrowser_backbrowser_forwardbrowser_reload
Inspection
browser_get_urlbrowser_get_titlebrowser_snapshotbrowser_visible_text
browser_snapshot is bounded by default and may be restricted with a semantic/CSS scope,
interactiveOnly, per-node maxChildren, maxDepth, includeBoundingBoxes, maxChars, and
maxBytes. Its structured result reports every applied bound, intentional tree omission, and
character/UTF-8 byte count. When either response cap is reached,
partial=true, truncation.truncated=true, and contentFormat=aria-yaml-fragment; do not parse
that fragment as a complete ARIA YAML document. Password values remain redacted. Set
includeRefs=true to receive at most maxRefs (default 50, maximum 100) opaque interactive-element
refs for immediate follow-up actions. Refs expire after 30 seconds, are scoped to the exact
session/page, and become stale after navigation, DOM replacement, page close, expiry, or a newer
ref snapshot. A non-null nextCursor continues the same immutable captured serialization without
rereading a changed DOM. Cursors are scoped to the exact session/page, expire after 30 seconds, and
become stale after navigation, page close, quota eviction, or shutdown. At most four paginated
snapshots and 1,000,000 Unicode code points per captured snapshot are retained per page.
Before native ARIA serialization, BrowserMesh also rejects a scope exceeding 20,000 DOM/text nodes
or 2,000,000 source characters. This pre-capture budget limits browser-side work independently of
the smaller per-response and retained-cursor bounds.
Observability
browser_observe
One tool reads all four recorded sources, selected by source: console, pageError, network,
or requestFailed. It requires an explicit sessionId and pageId, and echoes source so results
read into one buffer stay distinguishable.
Console and page-error reads are metadata-only by default; set includeText=true for bounded,
best-effort-redacted evidence. The two network sources carry no text and reject that flag rather
than returning a metadata-only answer that looks complete. Use nextCursor as the next
non-destructive sinceEventId checkpoint. Always inspect gap and droppedCount before concluding
that an event was absent. Text may be truncated further to satisfy the total response-byte limit;
the event and its cursor are still returned so pagination cannot stall. BrowserMesh never captures
console argument objects or raw error stacks.
Network reads expose only correlated request/response/request-failed metadata: a bounded request
ID, method, sanitized URL, resource type, status, duration, and safe failure classification where
applicable. Credentials and fragments are removed and sensitive query values are redacted before
storage. Headers, bodies, cookies, storage, service-worker traffic, WebSockets, data: URLs, and
blob: URLs are excluded. Page-originated HTTP(S) EventSource requests are included as ordinary
network metadata. HTTP error responses such as 500 appear under source: "network"; only
transport-level failures appear under source: "requestFailed".
Before 0.2 these were four tools —
browser_console_list,browser_page_errors_list,browser_network_list, andbrowser_failed_requests_list— publishing four copies of one contract. Pass the matchingsourceinstead.
Interaction
browser_clickbrowser_double_clickbrowser_hoverbrowser_focusbrowser_checkbrowser_uncheckbrowser_scroll_into_viewbrowser_scrollbrowser_drag_and_dropbrowser_fillbrowser_pressbrowser_select_option
These typed operations accept exactly one semantic/CSS locator or short-lived snapshot ref. They are explicitly
addressed, bounded by timeoutMs, cancellation-aware, and serialized with all browser work in the
owning session. check and uncheck ensure the requested state idempotently. browser_scroll
accepts bounded integer pixel deltas (deltaX and deltaY from -1,000,000 through 1,000,000),
while drag-and-drop resolves both source and target with the same strict locator semantics. None of
these tools exposes arbitrary page JavaScript.
Deterministic waits
browser_waitbrowser_action_and_wait
browser_wait observes one passive, typed condition through the owning session queue: an exact or
safe-glob URL, domcontentloaded/load, locator state, or bounded text presence/absence. Text
matching is a case-sensitive substring check against at most the first 1,000,000 characters of
the page body's rendered innerText; absent means that substring is not present in that bounded
observation. Caller regular expressions, JavaScript predicates, arbitrary sleeps, and
networkidle are not supported.
Do not queue a passive wait before the same-session action expected to satisfy it.
browser_action_and_wait registers a typed navigation, HTTP response, popup, or dialog waiter first
and then performs one click or key press under one shared deadline. Returned response URLs remove
credentials and fragments and redact common sensitive query values. A popup is assigned a new
managed pageId in the same session with isDefault=false; overflow popups are closed before
LIMIT_EXCEEDED is returned. Dialogs are handled atomically with an expected type and accept/dismiss
choice because a blocking dialog cannot be safely inspected later. Prompt input and returned dialog
metadata are bounded.
browser_action_and_wait addresses its action with target, taking a semantic/CSS locator or a
snapshot ref exactly like the standalone interaction tools. Neither result restates the request:
browser_wait returns satisfied, and browser_action_and_wait returns the observed event. The
caller already holds the condition and action it sent, and operationId correlates the result.
Capture
browser_screenshot
Screenshots are returned as MCP image content instead of being written to a caller-controlled
filesystem path. The optional capture mode selects the viewport, the full scrollable page, or one
strictly resolved semantic/CSS element; the default remains the viewport. Structured output reports
actual PNG width, height, and encoded bytes. BrowserMesh measures CSS-pixel dimensions before capture
and validates actual PNG dimensions and bytes afterward. Full-page and element modes capture the
fixed measured clip, so later page growth cannot expand native image allocation. Configured
overflow returns LIMIT_EXCEEDED and does not poison the session queue.
Persistence
browser_state_savebrowser_state_listbrowser_state_remove
browser_session_create accepts an optional stateId.
Without stateId, it creates a fresh isolated context.
With stateId, it initializes the new context using a previously saved BrowserMesh state.
Saved-state count, individual bytes, and aggregate bytes are centrally bounded. Quota checks and atomic replacement are serialized across all state IDs; a rejected replacement preserves the old state. Existing files are size-checked and read with a hard bound before JSON parsing.
browser_session_create also accepts an optional contextSettings object for an isolated viewport,
device scale factor, locale, timezone, color scheme, reduced-motion preference, and user agent. The
session result returns the normalized effective settings. Use separate sessions for different
device/accessibility/permission profiles. Geolocation is optional and the only supported browser
permission is an explicit grant to one absolute HTTP(S) origin. Wildcards and arbitrary permission
names are rejected.
browser_session_create({
name: "mobile-fr",
contextSettings: {
viewport: { width: 390, height: 844 },
deviceScaleFactor: 3,
locale: "fr-FR",
timezoneId: "Europe/Paris",
colorScheme: "dark",
reducedMotion: "reduce"
}
})
Geolocation access must be scoped to the exact application origin:
browser_session_create({
name: "local-map-test",
contextSettings: {
geolocation: { latitude: 41.3111, longitude: 69.2797, accuracy: 25 },
permissions: [
{ permission: "geolocation", origin: "https://maps.example.test" }
]
}
})
The permission is isolated to that session context and is removed when the session closes. Saved storage state does not contain or restore BrowserMesh permission grants.
Example conceptually:
browser_session_create({
name: "buyer",
stateId: "buyer-auth"
})
Session labels
A session may have:
- an optional human-readable
name; - optional string metadata.
For example an external AI client may label sessions:
role=buyer
role=seller
account=work
These values are neutral workflow labels only.
They do not create:
- internal Agent entities;
- ownership principals;
- permissions;
- mailboxes;
- message channels;
- LLM identities.
MCP tool discovery
BrowserMesh tool descriptions are part of the product contract.
Descriptions must explain both what a tool does and when an AI client should use it.
For example, the description for browser_session_create must make it clear that separate sessions should be used for:
- different users;
- different accounts;
- different roles;
- different authentication states;
- independent parallel browser workflows.
The goal is that a user can say:
Test this application as a buyer and an administrator.
without having to manually instruct the AI to call browser_session_create twice.
Every discovered tool also publishes a human-readable title, an object-root outputSchema, and
reviewed MCP risk hints (readOnlyHint, destructiveHint, idempotentHint, and openWorldHint).
These hints improve client UX only; BrowserMesh never treats them as authorization.
Successful calls return schema-validated structuredContent with direct semantic fields. For
example, browser_session_create exposes operationId, session, and initialPage directly,
without a nested value.value envelope. A concise JSON text block remains for text-only clients.
Screenshots retain their in-memory MCP image block and add structured PNG/correlation metadata.
Application failures use isError: true and a bounded JSON error containing a stable code, safe
message, optional sanitized details, and operationId correlation when the runtime accepted the
operation. Raw causes, stacks, cycles, non-JSON values, and secret-bearing detail fields never cross
the MCP boundary. SDK input-schema failures remain distinguishable as MCP input-validation errors.
⭐ Built for agent-friendly workflows
BrowserMesh is designed for predictable workflows with AI coding and browser agents. On connect it
returns a short MCP instructions string — the one channel that reaches an agent before its first
tool call — covering three things: address every session explicitly, support the project if you find
it useful, and how to report a bug.
BrowserMesh MCP questions
How do I add BrowserMesh MCP to Claude Code?
Run claude mcp add multi-agent-browser-mcp -- npx -y browsermesh in your terminal. Add --scope user to make it available in every project.
How do I add BrowserMesh MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does BrowserMesh MCP provide?
It exposes 35 tools, including browser_runtime_info, browser_session_create, browser_session_list, browser_session_get, browser_session_close.
Is BrowserMesh a hosted service?
No, it is a local-only runtime that runs on your machine.
How do I install it using Claude Code?
You can add it using the command: claude mcp add browsermesh -- npx -y browsermesh