@anvailabs/agentbrowser-mcp

The MCP server for AgentBrowser. Two install paths, one source:

npm i -g @anvailabs/agentbrowser-mcp   # Node >= 18
# or: download the bun-compiled standalone binary from the GitHub Releases

The package is only the MCP stdio adapter — it proxies to an AgentBrowser service. Point it at one with AGENTBROWSER_BASE_URL (default http://localhost:5709).

Discover usage before inspecting source

tools/list includes headed-session, cookie-handoff and LAN policy guidance on the relevant tools. create returns both a sessionId and an initial pageId; set headless: false for a visible window on the server host. CLI session create only returns a session, so shell clients must also call page create.

When shell access is available, use agentbrowser --help and offline agentbrowser describe session create / describe navigate / describe plan --schema for examples and exact CLI syntax. AGENTBROWSER_BASE_URL configures this adapter; the CLI uses --base-url. Neither reconfigures the running REST server. An operator may set AGENTBROWSER_ALLOWED_CIDRS on agentbrowser-server at startup for specific authorized LAN hosts. This never relaxes loopback/metadata blocks or overrides session host restrictions. There is no per-tool policy-widening argument.

Cookie tool results contain credentials. Prefer the CLI's private-file export/import when appropriate, and verify the expected authenticated UI after seeding. See the quick reference.

Exposes AgentBrowser as a small set of high-level, safe, composable MCP tools (ADR-009). Raw engine operations — evaluate, routing, selectors, low-level input — are deliberately not exposed.

Tool surface

See the generated tool catalog for unbound and delegated surfaces, required arguments and output contracts. It comes from actual tools/list responses, with a digest over complete descriptions and schemas. The existing release artifact check rejects drift. Regenerate after building with node scripts/mcp-catalog-docs.mjs --write.

session inspects metadata and pages when given a sessionId. On a delegated connection the binding supplies that ID and the same response also includes current control status. The tool requires both session.control and page.observe; application mode therefore does not expose it. Delegated mode removes create/close/cookies and adds operation (operation status). AGENTBROWSER_MODE fixes one profile for the lifetime of the bridge connection. Reconnect to change profiles; clients may cache catalogs. Obtain the effective catalog from your own connection with tools/list; metadata never enlarges a session grant, and the service rejects a tool call that the bearer grant's profile does not allow even if a mismatched bridge advertises it.

qa, operations, appsec, bounty, and forms currently project the complete browser catalog. audit omits bulk autofill. application exposes only delegated operation reconciliation until T4 publishes typed application tools. These deliberate duplicates avoid fictional context savings; the generated catalog records exact result bytes for every profile and binding.

Protocol and result compatibility

The foundation candidate supports MCP 2024-11-05 and 2025-06-18. Explicit legacy clients keep text JSON and catalogs without output schemas/annotations. Newer or unknown requested versions are offered 2025-06-18; clients must support that returned version or disconnect. Missing initialization retains historical text behavior; clients should always perform the handshake. A connection cannot renegotiate while calls run.

Under 2025-06-18, autofill and plan advertise canonical urn:agentbrowser:autofill-report:v1 and urn:agentbrowser:plan-report:v1 schemas and return validated structuredContent plus identical serialized JSON text. Plan retains optional mode/revision metadata to preserve the existing SDK contract; the current server always supplies it. Other tools still return text JSON; no unqualified output schemas are invented. Both tools' annotations explicitly state that it mutates and is not safe to repeat. Hints are not authorization or proof of browser/backend support. The MCP tools specification defines the structured/text compatibility behavior.

Failed autofill and plan reports (ok: false) now set isError: true in both protocols while retaining complete receipt/result JSON. This changes error signaling from 1.8.18; clients should inspect the retained report and must not treat it as a retry instruction. Successful verify: none reports do not establish verification or application commit. Invalid upstream bulk reports return a sanitized text error with uncertainty instructions, never a fabricated structured success or an automatic second write. Errors before a valid report exists remain text diagnostics without structured content.

This transport qualification does not yet certify structured-result consumption by installed Victor, Codex or Claude clients. That remains T8 harness acceptance.

For qualified native forms, prefer autofill; inspect each field's verification receipt and preserve uncertain writes. For explicit heterogeneous steps use snapshot → plan — see the main README.

Multiple pages and large research results

create still returns its initial pageId. Use page_create with that sessionId and an optional HTTP(S) url to create another page in the same cookie context. Use pages to discover page IDs, including adopted popups; never invent an ID or expect navigation to create a page implicitly. These tools delegate to the existing SDK, and the service remains the authorization/policy owner. The equivalent shell interfaces remain agentbrowser page create --help and agentbrowser page list --help.

Bound creation requires operationId chosen before dispatch. Controlled sessions deduplicate that ID, but operation status does not retain the resulting page ID. Ordinary sessions made by create do not acquire deduplication from an ID alone. Do not automatically retry an uncertain create in either case; inventory is not proof of which page a concurrent create produced. A general explicit-page quota and result correlation remain follow-ups, separate from the existing popup cap.

extract preserves complete data and evidence within maxBytes. Its default ceiling is 1 MiB of compact JSON including evidence; the operator can raise the ceiling with AGENTBROWSER_EXTRACT_MAX_BYTES before starting the service. Raw HTML size is not the extracted result size. Over-limit results fail explicitly, with no partial JSON. The MCP text envelope is separately serialized and can be larger. Any overflow files written by Claude or another harness belong to that harness; AgentBrowser does not define their paths.

For the reproducible headed research smoke and its limits, see research qualification.

Running it

Release consumers: the single binary (recommended)

Download agentbrowser-mcp-<target> from the GitHub releases (verify against sha256sums.txt), then point any MCP client at it — no Node, no pnpm, no repo checkout:

# ~/.victor/mcp.yaml
mcpServers:
  agentbrowser:
    command: /usr/local/bin/agentbrowser-mcp
    env:
      AGENTBROWSER_BASE_URL: http://localhost:5709

The binary is only the MCP adapter (TD-BROWSER-5 scope boundary): it needs a reachable AgentBrowser server over AGENTBROWSER_BASE_URL for anything beyond the protocol handshake. Deploy the server once (release tarball, or node packages/api/dist/bin.js); every consumer process spawns the binary.

Development: from the workspace

pnpm --filter @anvailabs/agentbrowser-mcp build
node packages/mcp-server/dist/bin.js

Environment

Building and gating the binary

pnpm --filter @anvailabs/agentbrowser-mcp compile   # -> dist-bin/agentbrowser-mcp (needs bun)
pnpm --filter @anvailabs/agentbrowser-mcp smoke     # stdio handshake + full tool-catalog gate

Cross-compile with node scripts/compile.mjs --target=bun-linux-arm64 --outfile=.... CI runs both on every PR (Bun compile + smoke job), and every v* tag publishes the five-target release matrix — see docs/td/TD-BROWSER-5-single-binary-mcp-distribution.md.