How Scout works
A technical deep-dive into Scout's browser automation environment: runtime surfaces, platform adapters, 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.
01Agent client
MCP over HTTPAny 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, extension runtime, platform adapter, or payment surface. It sees a standard agent interface with declared tools and schemas.
Claude DesktopCursorClineCustom agentsCustom MCP clients02Runtime surfaces
Streamable HTTP MCPRuntime surfaces and platform adapters. Browser, canvas, extension, and payment are capability surfaces of the browser runtime, while platform adapters pair through their own 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 surfacepayment surfacefigma adapter03Identity and metering
Bearer authShared 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 meter04Capability runtimes
CDP, native APIs, service adaptersExecution 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 handlersBrowser connector coverage
Browser automation is Scout's broadest connector server. These groups map to browser/runtime operations exposed through MCP tools.
PageCore page lifecycle. Navigate URLs, capture screenshots, generate PDFs, manage navigation history.
navigate()reload()captureScreenshot()printToPDF()getNavigationHistory()RuntimeJavaScript execution context. Run code in the page, capture console output, handle exceptions.
evaluate()callFunctionOn()consoleAPICalled eventexceptionThrown eventNetworkFull network stack access. Intercept requests, capture responses, manage cookies at protocol level.
requestIntercepted eventsetCookies()getCookies()getResponseBody()DOMDirect DOM access. Query nodes, read and modify attributes, extract HTML without JavaScript evaluation.
querySelector()getAttributes()getOuterHTML()setAttributeValue()AccessibilityAccessibility tree snapshot. The foundation of Scout's snapshot tool, providing structured semantic content without parsing HTML.
getFullAXTree()queryAXTree()InputProgrammatic input injection. Simulate clicks, keystrokes, and touch gestures at the protocol level.
dispatchMouseEvent()dispatchKeyEvent()dispatchTouchEvent()synthesizePinchGesture()EmulationDevice and environment overrides. Emulate mobile devices, spoof geolocation, override timezone.
setDeviceMetricsOverride()setGeolocationOverride()setTimezoneOverride()TargetTab 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.
01Client 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.
02Identity is resolved
The shared connector runtime resolves firebaseBearerAuth, establishes the worker identity, resolves the caller's allowance, and prepares the request context.
03Tool 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.
04Runtime 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.
05Result 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 + contentOwns 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-evaluateInteractor
interactionHandles 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-highlightNetwork Manager
networkMonitors 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-websocketStorage Manager
storageManages all browser storage. Reads and writes cookies, localStorage, sessionStorage, and the clipboard.
Seed auth tokens into localStorage before running a test
browser-cookiesbrowser-storagebrowser-clipboardMedia Controller
mediaControls 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-transcribeDebugger
debugDiagnoses page health. Captures console output, reads performance timings, monitors DOM memory.
Detect memory leaks in a long-running SPA session
browser-consolebrowser-metricsbrowser-memoryEmulator
emulationControls 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-throttleHow 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.