Architecture

How Scout works

A technical deep-dive into Scout's browser automation environment: runtime surfaces, identity-aware request handling, and capability boundaries that stay separated by design.

The runtime stack

Scout is organized as a clean separation of concerns. Each layer has a single responsibility and communicates through well-defined protocols.

01

Agent client

MCP over HTTP

Any AI client that speaks a protocol Scout supports. It connects to the runtime surface whose capability boundary matches the task and sends typed tool calls.

The client does not need to know whether a capability is backed by a browser session, canvas surface, or extension runtime. It sees a standard agent interface with declared tools and schemas.

Claude DesktopCursorClineCustom agentsCustom MCP clients

02

Runtime surfaces

Streamable HTTP MCP

Runtime surfaces. Browser, canvas, and extension are capability surfaces of the browser runtime.

Surfaces are built from the shared runtime. They register typed tools, mount identity-aware auth, check the caller's allowance, and dispatch tool calls into the runtime that owns the capability.

browser runtimecanvas surfaceextension surface

03

Identity and metering

Bearer auth

Shared request boundary for Scout's runtime surfaces. Every surface resolves the caller, establishes the worker identity, and meters capability usage before execution.

OAuth-capable clients can use Firebase-backed auth. Scout MCP tokens support clients and automation environments that cannot complete browser OAuth. Chrome extension model calls use the user's configured AI provider key through the Mastra server.

Firebase ID tokensScout MCP tokensworker identityallowance checkusage meter

04

Capability runtimes

CDP, native APIs, service adapters

Execution runtimes. Agents call runtime surfaces for clean hosted sessions; the Chrome extension connects to the Mastra server when an agent needs the user's real browser state.

The extension is no longer the whole architecture. It is the app runtime for real-browser workflows. Durable session transports keep the Mastra server and browser state coordinated without making every surface an extension bridge.

clean Chromium sessionsextension-owned sessionsCDP adaptersdurable streamscapability handlers

Browser connector coverage

Browser automation is Scout's broadest connector server. These groups map to browser/runtime operations exposed through MCP tools.

Page

Core page lifecycle. Navigate URLs, capture screenshots, generate PDFs, manage navigation history.

navigate()reload()captureScreenshot()printToPDF()getNavigationHistory()

Runtime

JavaScript execution context. Run code in the page, capture console output, handle exceptions.

evaluate()callFunctionOn()consoleAPICalled eventexceptionThrown event

Network

Full network stack access. Intercept requests, capture responses, manage cookies at protocol level.

requestIntercepted eventsetCookies()getCookies()getResponseBody()

DOM

Direct DOM access. Query nodes, read and modify attributes, extract HTML without JavaScript evaluation.

querySelector()getAttributes()getOuterHTML()setAttributeValue()

Accessibility

Accessibility tree snapshot. The foundation of Scout's snapshot tool, providing structured semantic content without parsing HTML.

getFullAXTree()queryAXTree()

Input

Programmatic input injection. Simulate clicks, keystrokes, and touch gestures at the protocol level.

dispatchMouseEvent()dispatchKeyEvent()dispatchTouchEvent()synthesizePinchGesture()

Emulation

Device and environment overrides. Emulate mobile devices, spoof geolocation, override timezone.

setDeviceMetricsOverride()setGeolocationOverride()setTimezoneOverride()

Target

Tab management. Attach sessions, list targets, create new tabs, manage the CDP session lifecycle.

attachToTarget()detachFromTarget()getTargets()createTarget()

Browser execution lifecycle

What happens between an MCP client connecting to the browser connector and Scout returning a browser result.

01

Client connects

The MCP client connects to the hosted browser connector over streamable HTTP and completes OAuth or presents a Scout MCP token for non-interactive use.

02

Identity is resolved

The shared connector runtime resolves firebaseBearerAuth, establishes the worker identity, resolves the caller's allowance, and prepares the request context.

03

Tool is dispatched

The connector looks up the browser tool, validates its schema-backed arguments, and dispatches the call to the browser handler that owns that behavior.

04

Runtime executes

The browser runtime launches or attaches to the requested session. Hosted sessions provide clean automation; extension-backed sessions preserve a user's real tabs and authenticated browser state.

05

Result returns

The handler returns a structured MCP result. Subsequent calls can use returned refs for tabs, frames, elements, files, downloads, dialogs, network events, and session state.

Agent division of labor

Scout routes browser work to focused specialists that observe before acting and delegate multi-step domain work to one another.

Orchestrator

session + navigation + content

Owns session management, navigation, and content tools directly. Delegates multi-step domain work to specialists.

Navigate to URL, take snapshot, extract data, attach session

browser-tabsbrowser-sessionbrowser-navigatebrowser-snapshotbrowser-extractbrowser-evaluate

Interactor

interaction

Handles all user input simulation. Observes snapshots before acting, retries with corrected selectors on failure.

Fill a multi-step checkout form with dynamic field validation

browser-interactbrowser-attachbrowser-dialogbrowser-highlight

Network Manager

network

Monitors and manipulates network traffic. Intercepts API calls, records HAR files, manages certificates.

Intercept GraphQL responses and mock them for testing

browser-networkbrowser-routebrowser-unroutebrowser-harbrowser-securitybrowser-websocket

Storage Manager

storage

Manages all browser storage. Reads and writes cookies, localStorage, sessionStorage, and the clipboard.

Seed auth tokens into localStorage before running a test

browser-cookiesbrowser-storagebrowser-clipboard

Media Controller

media

Controls all media output. Screenshots, screencasts, PDF generation, video frame capture, and downloads.

Record a full user flow as a video for documentation

browser-screenshotbrowser-screencastbrowser-pdfbrowser-mediabrowser-downloadbrowser-transcribe

Debugger

debug

Diagnoses page health. Captures console output, reads performance timings, monitors DOM memory.

Detect memory leaks in a long-running SPA session

browser-consolebrowser-metricsbrowser-memory

Emulator

emulation

Controls device and environment simulation. Emulates mobile devices, throttles CPU/network, emulates vision deficiencies.

Test a checkout flow with custom viewport, mobile user agent, and 3G-throttled connection

browser-emulatebrowser-resizebrowser-visionbrowser-cpubrowser-throttle

How Scout remembers

Scout keeps a small, scoped memory model so agents can reuse observations across tabs without hoarding conversation history.

Working Memory

Per tab (thread-scoped)

Structured per-tab state updated by the agent. Tracks the current URL, page title, active session ID, user goal, and key observations.

Tab A tracks that the user is on step 3 of a checkout flow. Tab B tracks a dashboard URL independently.

Observational Memory

Per extension (resource-scoped)

Auto-extracted semantic observations shared across all tabs for the same extension. Agent in Tab B can read discoveries made by Tab A.

Tab A discovers the API base URL. Tab B can use it without re-discovery.

Message History

Per tab (thread-scoped, last 20)

The last 20 conversation turns per tab. Each tab maintains an independent conversation history that survives WebSocket reconnects.

Resuming a long research session after reconnecting.

Operating concepts

Practical implications of Scout’s runtime, authentication, and reference model.

Users choose which connectors to expose in their MCP client, while the connected runtime uses those tools on the workflow's behalf.

Connectors are configured separately so each workflow only exposes the capabilities it actually needs.
The extension follows Scout's app-side tool flow rather than appearing as another public connector users install directly.
Use the extension path only when the task depends on your real tabs, cookies, or authenticated browser state; otherwise keep the workflow on isolated connector sessions.

OAuth is the default for interactive MCP clients. Scout MCP tokens are a fallback for non-interactive environments.

Interactive MCP clients should discover Scout's auth metadata automatically when they connect to https://mcp.scout.i.ng/browser.
Use Scout MCP tokens only for CI, scheduled jobs, or MCP clients that cannot complete the browser sign-in flow.
Once a request reaches Scout, both auth modes resolve to the same account identity and worker identity shape.

Scout uses short typed refs so workflows can act on stable handles instead of repeating selectors or runtime IDs.

@s identifies a session, @t a tab, @f a frame, and @e an element discovered in a snapshot.
Element refs are snapshot-scoped, so re-snapshot after the DOM changes instead of reusing stale handles.
For parallel runs, use Scout's coordination primitives to split work across tabs without losing session boundaries.

Guardrails keep automations bounded in cost, scope, and risk.

browser-task runs are step-limited and tool output is truncated so agents do not spiral into runaway loops or oversized context payloads.
Use snapshot filtering to keep token usage under control: trim decorative nodes, scope to the relevant container, and keep depth tight.
Prefer hosted connector sessions for untrusted work. Use extension-backed sessions only when existing authenticated state is part of the job.
Active connector work counts toward your Agent Hour allowance, while model inference remains BYOK when your workflow calls external providers directly.

Safe operation

Keep capability, identity, and browser-state boundaries explicit.

Do not default to production data when connecting an MCP client. Prefer development or staging environments, and keep real customer data away from exploratory AI workflows whenever possible.

Leave manual approval enabled in your MCP client and review tool calls before execution. Prompt injection remains a real risk whenever the model can read untrusted page content and then decide what to run next.

Prefer hosted browser connector sessions for scraping, testing, and untrusted sites. Reserve the extension path for workflows where you explicitly want your real browser cookies, sessions, and authenticated state.

Scout MCP tokens are powerful credentials. Store them in secret managers, scope them narrowly, rotate them when workflows change, and revoke them when an integration ends.

Reduce the available action set when possible. Install or configure only the connector MCP servers needed for the workflow, and use the shortest-lived credential that still satisfies the automation.