Stop wasting 48K tokens to read a webpage. Substrate compresses a typical content page into roughly 1–4K tokens your LLM can actually use — vs. ~48K of raw HTML.

Substrate is an MCP server that gives your AI agent eyes and hands on the web. It extracts a compressed semantic graph of any webpage — buttons, inputs, links, dropdowns, checkboxes — with precise pixel coordinates, and handles clicking, typing, and selection via spatial coordinates. No CSS selectors. No xpaths. No hallucination.

Why It Matters

Every other browser automation approach burns tokens on noise:

Approach	Tokens	Extraction	What Your LLM Gets
Raw HTML (`page.content()`)	~48,000	5ms	Full DOM tree — scripts, styles, hidden elements, ad markup. LLM drowns in noise and hallucinates clicks on invisible elements.
Vision (screenshot + OCR)	~8,000	~800ms	A pixel blob. LLM can "see" the page but can't target anything precisely. Clicks land 20px off. Forms fail.
Substrate	~1,000–4,000	~10–30ms	Structured JSON: what each element is, where it is, what state it's in. LLM clicks the right thing on the first try.

The math: a ~110-element content page (say, Wikipedia) compresses to roughly ~2,300 tokens — about 1.8% of a typical 128K context window. You can fit roughly ~55 page extractions before the LLM runs out of room. With raw HTML, you get 2.

Token figures are order-of-magnitude, measured live on representative pages (example.com ~84 tok, Wikipedia ~3.5K, Hacker News front page ~4.4K, extraction 8–58ms). They scale with page density; the extractor caps output at MAX_ELEMENTS=400, so very dense pages are truncated rather than emitted in full. The math is arithmetic: on a ~2.3K-token page, ⌊128K/2.3K⌋ ≈ 55 extractions.

The real win — shorter action loops:

Without Substrate:                          With Substrate:
navigate → screenshot                       navigate
→ "I see a button" → click (wrong)          → {btn id=3 "Submit" [640,400]}
→ screenshot → "ah, more right"             → click(3) → done.
→ click → "not that either"                 
→ screenshot → ...                          2 tool calls. Task complete.
8-12 tool calls. Task complete.

That's not a marginal improvement. That's 5-6x fewer API calls, 5-6x less latency, and 5-6x lower cost per web task.

How It Works

Substrate runs as a headless Chromium browser via the Model Context Protocol (MCP). Your LLM agent talks to it through 10 simple tools:

Tool	What It Does
`navigate`	Load a URL, get back the page graph (capped at 400 elements)
`click`	Click any element by its numeric ID
`type_text`	Type into an input field (auto-clears first)
`select_option`	Pick a dropdown option by value
`press_key`	Press a keyboard key (Escape, Enter, Tab, arrows, modifiers)
`scroll`	Scroll up/down by 80% of viewport
`screenshot`	Get a visual snapshot + the graph together
`go_back` / `go_forward`	Browser history navigation
`get_current_url`	Check where you are

Every navigation and interaction tool returns the same compressed graph (get_current_url returns just the URL; screenshot returns the image plus the graph). Your LLM reads the graph, picks an element ID, and calls the next tool. No image interpretation. No HTML parsing. Just IDs and coordinates.

Zero-Config Setup

Add this to your MCP configuration:

{
  "mcpServers": {
    "substrate-browser": {
      "command": "npx",
      "args": ["-y", "substrate-browser"]
    }
  }
}

(Playwright handles Chromium on first run. Requires Node.js 20+).

Running from source

git clone https://github.com/substrate-browser/substrate-browser.git
cd substrate-browser
npm install
npx playwright install chromium
npm run build
npm start

Environment Configuration

Variable	Default	Purpose
`SUBSTRATE_PROXY`	(none)	Optional egress proxy URL (`http(s)://` or `socks5(socks4)://`). When set, all Chromium traffic is routed through it — the strongest defense against DNS-rebinding (the re-resolution happens at the remote proxy, not local DNS). Recommended: a proxy configured to allow outbound to public IPs only.
`SUBSTRATE_PROXY_BYPASS`	(none)	Comma-separated hosts to exclude from proxying. Use with care: bypassed hosts are not covered by the proxy's public-IP allowlist. Requires `SUBSTRATE_PROXY`.
`SUBSTRATE_VIEWPORT_WIDTH` / `SUBSTRATE_VIEWPORT_HEIGHT`	`1280` / `800`	Browser viewport dimensions (integers 320–7680). Controls screenshot resolution and the coordinate space your agent sees. Set, e.g., a mobile viewport or a higher-res canvas. Invalid values fail at startup rather than silently.

Invalid or unsafe values for any of these fail loudly at server startup.

Core Features

Token-First JSON Extraction: 95% less bloat. Elements with direct visible text — interactive ones plus meaningful labels, headings, and copy — reach your LLM; scripts, styles, ad markup, hidden DOM, and most pure-layout nodes are dropped.
Spatial Coordinate Engine: Absolute (x,y) pixel bounds. Handles position: fixed/sticky. Real OS-level mouse clicks — no CSS selectors that break on every React redesign.
Shadow DOM Penetration: Pierces Web Components automatically. Works on React, Vue, Angular, Svelte — any framework that uses Shadow Roots.
10 Tool Actions: Navigate, click, type, select dropdowns, press keys, scroll, screenshot, go back/forward, check URL. Covers the full web interaction loop.
Ad-Blocker & Dialog Deflection: Blocks tracking pixels and ad networks at the network layer. Auto-dismisses alert/confirm/beforeunload so they never hang your agent.
SSRF & DNS-Rebinding Protection: Blocks localhost, private IPs, IPv6 loopback/link-local/ULA/multicast, IPv4-mapped IPv6 (including 6to4, NAT64, and fully-expanded forms), cloud metadata endpoints, and dangerous protocols. Every navigation re-resolves the hostname behind an atomic guard, so a domain that flips to an internal IP mid-session is caught too — validated against an 81-case adversarial SSRF audit. Your agent can't hit internal services.
Zero-Infra Footprint: A ~21KB npm package with no servers, no SaaS backend, no database — just npx -y substrate-browser. Requires only Node.js 20+ and Playwright's Chromium (auto-installed on first run). Works anywhere your MCP client does.
Viewport Streaming: Only extracts visible elements. Your agent scrolls like a human to discover more content, keeping each response tiny.

Compressed Graph Schema

Every tool returns a compressed JSON object:

{
  "t": "Page Title",
  "u": "https://example.com",
  "s": [0, 4800, 800],
  "n": 42,
  "e": [
    [1, "btn", "Submit", [640, 400, 120, 40], 1],
    [2, "inp", "Email", [640, 340, 200, 30], 1, {"v": "hello"}],
    [3, "btn*", "Fixed Header", [0, 0, 1280, 50], 1],
    [4, "lnk", "Docs", [100, 200, 80, 20], 1, {"href": "/docs"}],
    [5, "sel", "Country", [100, 260, 200, 30], 1, {"v": "us", "opts": "US|UK|DE|FR"}],
    [6, "chk", "Accept", [100, 300, 200, 30], 1, {"c": true}]
  ]
}

Field	Meaning
`t`	Page title
`u`	Current URL
`s`	`[scrollY, scrollHeight, viewportHeight]`
`n`	Total elements extracted
`e`	Element array (see below)

Each element [id, role, text, [x, y, w, h], actionable, state?]:

Index	Field	Description
0	`id`	Stable numeric ID for click/type/select
1	`role`	Element type (see role codes below)
2	`text`	Visible text (truncated to 100 chars)
3	`[x,y,w,h]`	Bounding box in pixels
4	`actionable`	`1` if the element can receive clicks, `0` otherwise
5	`state`	Optional object (see state keys below)

Role Codes

Code	Element
`lnk`	Link (`<a>`)
`btn`	Button (`<button>`, `<input type="submit/button">`)
`inp`	Text input (`<input>`, `<textarea>`)
`sel`	Dropdown/select (`<select>`)
`chk`	Checkbox (`<input type="checkbox">`)
`rdo`	Radio (`<input type="radio">`, `role="radio"`)
`cmb`	Combobox (`role="combobox"`)
`sld`	Slider (`<input type="range">`, `role="slider"`)
`spin`	Spinbutton (`role="spinbutton"`)
`h1`–`h3`	Headings
`sum`	Summary (`<summary>`)
`det`	Details (`<details>`)
`vid`	Video (`<video>`) — includes `{src, paused}` state
`aud`	Audio (`<audio>`) — includes `{src}` state
`cvs`	Canvas (`<canvas>`) — aria-label/title as text
`ifr`	Iframe (`<iframe>`) — includes `{src}` state

A role ending in * (e.g. btn*) means the element is fixed/sticky-positioned. Its coordinates are viewport-relative, not page-relative.

State Keys

Key	Applies to	Meaning
`c`	`chk`, `rdo`	`true` if checked
`v`	`inp`, `sel`	Current value
`opts`	`sel`	Pipe-separated list of available options
`href`	`lnk`	Link destination URL (truncated to 80 chars)
`o`	`det`	`true` if details element is open
`x`	any	`true` if `aria-expanded="true"`
`sel`	any	`true` if `aria-selected="true"`

Elements are sorted by Y coordinate (top to bottom), then by X coordinate (left to right).

Programmatic Usage

You can use Substrate programmatically in your own Node.js automation loops. See /examples/basic_agent.js for a working example that connects to the MCP server as a client.