Leapfrog MCP

The Problem

Playwright MCP sends ~14,000 tokens for a content-heavy page like Hacker News. Most of that is noise. Your context window fills up. Your agent gets confused. You pay for it.

Leapfrog sends ~1,400 tokens. Same page. Same information. Up to 10x less noise.

┌─────────────────────────────────────────────────────┐
│  Playwright MCP                                     │
│  ████████████████████████████████████████  ~14,000   │
│                                                     │
│  Leapfrog                                           │
│  █████                                    ~1,400    │
└─────────────────────────────────────────────────────┘
          tokens per page (Hacker News, real test)

Savings range from 2-10x depending on page complexity. Content-heavy pages see the biggest wins. Dense forms see the smallest. The median across real-world sites is ~4-5x.

Related MCP server: MCP Browser

Quick Start

npx leapfrog-mcp --doctor          # verify everything works
npx leapfrog-mcp --stealth-audit   # test all 19 stealth patches
npx leapfrog-mcp --config          # print MCP config to paste

Add to ~/.mcp.json (Claude Code) or your editor's MCP config:

{
  "leapfrog": {
    "command": "npx",
    "args": ["-y", "leapfrog-mcp"],
    "env": {
      "LEAP_MAX_SESSIONS": "15",
      "LEAP_TILE": "true",
      "LEAP_HUD": "true",
      "LEAP_AUTO_CONSENT": "true"
    }
  }
}

Leapfrog uses playwright-core (15MB) instead of playwright (1.6GB) and does not bundle a browser. Either:

• Set LEAP_CHANNEL=chrome to use your installed Chrome/Chromium (recommended)

• Or run npx playwright-core install chromium to install the bundled Chromium binary

• Or set LEAP_CDP_ENDPOINT to connect to an already-running Chrome instance

Feature Matrix

Stealth

Leapfrog ships 19 anti-detection patches enabled by default (LEAP_STEALTH=true). Four modes:

• true (default) — all 19 patches active

• passive — removes automation signals only (webdriver, HeadlessChrome). Does NOT fake identity (WebGL, fonts, audio). Better for sites where trust matters more than evasion.

• auto — per-domain EXP3 bandit selects the optimal stealth configuration based on what's worked before

• false — no stealth patches

These cover the vectors that fingerprint services like CreepJS and fingerprint-pro actually check:

• Client Hints brands (strips HeadlessChrome)

• navigator.webdriver forced to undefined

• WebGL vendor/renderer (replaces SwiftShader with real GPU strings)

• Connection RTT (non-zero)

• Alert dismiss timing (human-speed delay)

• Window outer/inner height offset

• MIME type array population

• Platform inference from user agent

• chrome.app emulation

• iframe contentWindow protection

• Media codec spoofing (canPlayType)

• document.hasFocus() override

• Source URL comment stripping

• Custom UA + stealth coexistence (custom user agents no longer disable stealth context)

• CDP Runtime.enable detection (Error.prepareStackTrace filter)

• Permissions API spoofing (20+ permission types)

• AudioContext fingerprint noise (getChannelData/getFloatFrequencyData)

• WebRTC IP leak prevention (ICE candidate filtering)

• Font enumeration fingerprint spoofing

Per-session stealth control: pass stealth: false in session_create to disable for a specific session.

Humanization (Experimental)

Set LEAP_HUMANIZE=true to enable human-like browser interaction. This is opt-in and adds latency in exchange for more realistic behavior. Six modules:

• Mouse — Bezier curve paths with Fitts's Law timing and micro-tremor jitter

• Typing — Log-normal inter-key delays (200ms median), key dwell time, bigram-aware speed, rollover typing

• Scroll — Inertial simulation with ramp-up and momentum decay (touchpad/mouse-wheel physics)

• Pause — Inter-action "think" delays that simulate cognitive gaps between actions

• Fingerprint — Coherent browser fingerprint generation (platform, device memory, GPU, timezone)

• Utils — Shared math primitives (Box-Muller gaussian, distributions)

Page Classification

Every navigate and snapshot call automatically classifies the page type using weighted signal scoring (no LLM required). 18 types:

login · search-results · product · product-list · checkout · article · dashboard · form · error · challenge · landing · documentation · profile · media · feed · qa · ecommerce · unknown

Classification drives smarter snapshot extraction — login pages surface form fields, articles surface content, dashboards surface interactive elements.

Harness Intelligence

The harness tracks every action in a session and classifies outcomes:

• Action outcome classification — SUCCESS, SILENT_CLICK, NAVIGATION, WRONG_ELEMENT, BLOCKED, ERROR, PENDING

• Bot redirect detection — detects when a site redirects to a challenge or block page after an action

• Loop detection — warns when the agent is stuck clicking the same element, ping-ponging between URLs, or repeating actions

• Session memory — session_memory tool recalls actions after context window compression

Cookie Persistence

Persistent browser profiles now use context.cookies() + addCookies() instead of storageState(), which returns empty on persistent contexts. Auth state survives across sessions.

Adaptive Wait + Stealth Escalation

Navigate automatically retries with fallback strategies when pages fail to load:

1. Try load (fastest) — if empty, retry with networkidle (10s cap)

2. If networkidle times out (Amazon, ad-heavy sites), fall back to domcontentloaded

3. If blocked/challenged, escalate stealth: random delays → wait for JS challenge → rotate session with fresh fingerprint

4. Profile sessions (auth'd) never have their session destroyed — hard-capped at Level 2

Opt-out with autoRetry: false on navigate. Control max escalation with maxRetryLevel (0-5, default 3).

Record / Replay

Export a session's action history as a replayable recording, then replay it in new sessions:

• session_export — creates parameterized JSON or Playwright script from session history. @eN refs resolved to stable CSS selectors. Auto-detects emails, passwords, URLs as {{placeholders}}.

• session_replay — replays a recording with parameter overrides. Supports onError: 'stop' or 'skip'.

Turn one-off agent workflows into reusable automations.

Pagination Extraction

Extract data across multiple pages in a single tool call:

• Click-next — auto-detects "Next" buttons, pagination links, "Load more" buttons

• Infinite scroll — scrolls and waits for new content via DOM hash comparison

• URL pattern — increments ?page={page} or custom patterns

Replaces 3-4 tool calls per page. Cap: 50 pages, 100K total chars. Stops on: no next button, empty page, duplicate content, or bot detection.

Incremental Snapshots

The diff tool returns only what changed since the last snapshot — additions, removals, changes. Massive token savings for monitoring and polling workflows.

HUD Overlays (LEAP_HUD=true)

When running headed, Leapfrog overlays visual feedback on every session:

• Click ripple — expanding green circle at click coordinates (agent actions only)

• Zoom-to-target — browser zooms to 1.15x on the clicked element briefly so agents (and humans) can visually track what's happening in tiled windows

• Scroll-to-target — scrollIntoView before clicks so you can see what the agent is about to click

Minimal by design. No borders, no status bars, no cursor overlay — just the feedback that matters.

Multi-Terminal Tiling (LEAP_TILE=true)

Multiple Leapfrog instances share the screen via file-based coordination. Each instance tracks its own windows and a TilesCoordinator assigns global grid slots — no overlap, no manual arrangement. Set LEAP_TILE=true (or LEAP_TILE=master for the primary instance). Padding between tiles is configurable with LEAP_TILE_PADDING (default 8px).

Human Intervention

Leapfrog auto-detects situations that need a human — CAPTCHAs, login forms, OAuth redirects, Cloudflare challenges — and tries to self-resolve before pausing.

• Auto-resolves first: clicks reCAPTCHA checkboxes, Cloudflare verify buttons, generic verify/continue buttons, then a second-pass retry — all before asking for help

• External solvers: set LEAP_CAPTCHA_PROVIDER + LEAP_CAPTCHA_API_KEY for CapSolver, 2Captcha, or NopeCHA integration

• Learns what works: remembers which resolution method succeeded per domain and tries the known-good method first on revisit

• Detects reCAPTCHA, hCaptcha, Turnstile, login forms, OAuth redirects, Cloudflare challenges

• Tab title changes to "NEEDS HUMAN" when intervention is needed

• wait_for_human tool — agent calls when stuck, blocks until you resolve it or navigate past

Cookie Consent Auto-Dismiss (LEAP_AUTO_CONSENT=true)

Automatically dismisses cookie consent banners across 10 frameworks (OneTrust, CookieBot, TrustArc, Quantcast, Didomi, Cookielaw, Osano, Usercentrics, + generic) plus text-matching fallback. Per-domain selector caching for instant replay on revisit.

Tracing (LEAP_TRACE=true)

Per-session Playwright tracing with screenshots + DOM snapshots. Export ZIP files viewable at trace.playwright.dev via the session_export_trace tool. Auto-saves on session destroy.

Self-Improvement

Leapfrog learns from every visit. Per-domain knowledge persists at ~/.leapfrog/domains/{domain}.json — 9 dimensions, all automatic:

LRU eviction at 500 domains. Inspect with the domain_knowledge tool.

SSRF Hardening

URL validation blocks hex-encoded IPs (0x7f000001), octal notation (0177.0.0.1), CGNAT ranges (100.64.0.0/10), and redirect chains that resolve to internal addresses. Localhost and 127.0.0.0/8 are allowed by default for local dev workflows — set LEAP_BLOCK_LOCALHOST=true to block them.

The Ecosystem

Leapfrog uses pond metaphors to keep things memorable. Your agent is the frog.

All 36 Tools

Pond Management (11)

Navigation & Snapshots (12)

Tab Management (3)

Agent Intelligence (3)

Network & API Intelligence (7)

Environment Variables

Tests

 769 passing across 31 suites

Session management, snapshot engine, snapshot differ, network intelligence, tab management, security, SSRF protection, stealth patches (19), stealth enhanced, humanization (mouse, typing, scroll), page classification, harness intelligence, API intelligence, script executor, extended actions, HUD overlays, human intervention, cookie consent, domain knowledge, selector healing, stable elements, tile manager, bug regression, integration smoke, stress tests, benchmarks.

npm test

Requirements

• Node.js >= 20

• Chromium — use system Chrome (LEAP_CHANNEL=chrome) or install via npx playwright-core install chromium

License

MIT