browser-debugging

How to Monitor WebSocket Connections with AI Coding Assistants

Feb 1, 2025

Brenn Hill

Gasoline MCP is a browser extension and local server that captures real-time browser telemetry and exposes it to AI coding assistants via the Model Context Protocol. It is the only MCP browser tool that monitors WebSocket connections — capturing opens, closes, and individual messages so your AI assistant can reason about real-time traffic.

The Problem with Debugging WebSockets

WebSocket debugging is painful. Messages fly by in DevTools at a rate that makes manual inspection impractical. There is no search. There is no way to correlate a dropped connection with the UI bug it caused. And critically, your AI assistant cannot see any of it.

If you are building a chat application, trading platform, or collaborative editor, WebSocket issues are some of the hardest to debug. A missing message, a silent reconnection, a stale price feed — these problems live in the stream of events flowing over the wire. You cannot just copy-paste a WebSocket stream into your AI assistant. The data is ephemeral, and by the time you notice the bug, the evidence is gone.

What Gasoline Captures

Gasoline intercepts WebSocket activity at the browser level and buffers it for retrieval via MCP tool calls. Here is what your AI assistant gets access to:

Connection lifecycle events — open and close, including close codes and reasons
Sent and received messages — with precise timestamps for ordering analysis
Connection metadata — URLs, protocols, and connection state
Message payloads — full text content and binary frame sizes

All of this data is buffered locally on your machine and made available through a single MCP tool call. Your AI assistant can query the full WebSocket history for any tab at any time.

Use Cases

WebSocket monitoring becomes valuable anywhere real-time data flows through your application:

Chat applications — Diagnose message ordering bugs, detect dropped connections, and verify reconnection logic
Trading platforms — Identify price feed gaps, detect stale data, and audit message delivery timing
Collaborative editors — Debug OT/CRDT sync issues by inspecting the exact operation sequence exchanged between clients
Real-time dashboards — Detect data staleness and verify that subscriptions remain active after network interruptions
Multiplayer games — Analyze state synchronization problems by reviewing the full message exchange between client and server

No Other MCP Tool Does This

The major MCP browser tools — Chrome DevTools MCP, BrowserTools MCP, and Cursor MCP Extension — do not capture WebSocket events. They focus on console logs, network requests, and in some cases screenshots or browser automation. None of them intercept WebSocket frames.

If your application uses WebSockets, Gasoline is the only MCP tool that gives your AI assistant visibility into that traffic.

Example Workflow

You are debugging a chat application. Users report that messages stop appearing after a few minutes. The UI shows no errors. The console is clean.

You ask your AI assistant: “What’s happening with the WebSocket connection?”

The assistant calls Gasoline’s MCP tool and retrieves the WebSocket event log. It sees that the connection closed 30 seconds ago with code 1006 (abnormal closure) — no close frame was sent, which typically indicates a network interruption or server-side timeout. The assistant identifies that your server’s idle timeout is set to 60 seconds and your client has no heartbeat mechanism, then suggests adding a ping/pong keepalive interval.

Without Gasoline, this diagnosis would require manually watching the DevTools Network tab, catching the close event in real time, and interpreting the close code yourself.

How do I debug WebSocket issues with AI?

Install Gasoline and connect it to your AI coding assistant (Claude Code, Cursor, or Windsurf). Open your application in Chrome and reproduce the issue. Then ask your assistant about the WebSocket connection. Gasoline makes the full connection history available through MCP, so your assistant can inspect opens, closes, message sequences, and timing without any manual data gathering on your part.

Which MCP tools support WebSocket monitoring?

As of early 2025, Gasoline is the only MCP browser tool that captures WebSocket events. Chrome DevTools MCP, BrowserTools MCP, and Cursor MCP Extension provide console and network request capture but do not intercept WebSocket frames or connection lifecycle events.

Get Started

npx gasoline-mcp@latest

One command. No accounts. No configuration. WebSocket monitoring is enabled by default.

Learn more about WebSocket monitoring →

How to Give Cursor Access to Browser Console Logs

Jan 25, 2025

Brenn Hill

Cursor is a powerful AI code editor, but it has a blind spot: your browser. When your app throws an error at runtime, Cursor has no idea. You end up copying console output, screenshotting network tabs, and pasting fragments into chat — losing context every time.

Gasoline MCP is an open-source browser extension + MCP server that streams real-time browser telemetry to AI coding assistants. It connects Cursor directly to your browser so it can read console logs, network failures, and DOM state without you lifting a finger.

The Problem: Cursor Can’t See Your Browser

When something breaks in the browser, your workflow probably looks like this:

Notice a blank page or broken UI
Open Chrome DevTools
Read through the console errors
Copy the relevant ones
Paste them into Cursor and explain what happened

By the time Cursor sees the error, you’ve already done the hard part — finding it. And you’ve stripped away surrounding context: the network request that failed before the error, the sequence of console warnings that preceded it, the state of the DOM.

Cursor needs raw, continuous access to what the browser is doing.

Why Existing Approaches Fall Short

You could keep a DevTools window open and manually relay information to Cursor. But manual copy-paste has real costs:

Lost context. You copy one error but miss the failed API call that caused it.
Stale data. By the time you paste, the browser state has changed.
Friction. Every round trip between browser and editor breaks your flow.

Cursor supports MCP (Model Context Protocol) natively, which means any tool that speaks MCP can feed data directly into Cursor’s context. Gasoline uses this to bridge the gap.

What Cursor Can See Through Gasoline

Once connected, Cursor can query your browser for live telemetry:

Data Type	What Cursor Sees
Console logs	All `console.log`, `console.warn`, `console.error` output
JavaScript errors	Uncaught exceptions with full stack traces
Network requests	URLs, status codes, timing, headers
Network bodies	Request and response payloads (opt-in)
WebSocket messages	Real-time WS frame data
DOM state	Query elements, read attributes, check visibility

This is not a snapshot. Gasoline captures events continuously, so Cursor can ask “what happened in the browser?” at any point and get the full picture.

Setup: Four Steps

1. Start the Gasoline server

npx gasoline-mcp@latest

This downloads a single Go binary (no Node.js runtime, no node_modules/). It starts a local MCP server on your machine.

2. Install the Chrome extension

Install the Gasoline extension from the Chrome Web Store. It connects to the local server automatically.

3. Add the MCP server to Cursor

Open Cursor Settings, navigate to MCP, and add a new server with this configuration:

{
  "mcpServers": {
    "gasoline": {
      "command": "npx",
      "args": ["-y", "gasoline-mcp@latest"]
    }
  }
}

4. Ask Cursor to check the browser

In Cursor’s chat or agent mode, just ask:

“Check the browser for errors”

Cursor will call Gasoline’s MCP tools, read the captured telemetry, and respond with what it finds — and often fix the issue in the same turn.

Real Workflow: React Dashboard Blank Screen

Without Gasoline (5 steps):

See blank screen in browser
Open DevTools, find TypeError: Cannot read properties of undefined (reading 'map') in console
Switch to Network tab, notice the /api/dashboard request returned a 500
Copy both the error and the failed request details
Paste into Cursor, explain the situation, wait for a fix

With Gasoline (1 step):

Ask Cursor: “The dashboard page is blank. Check the browser and fix it.”

Cursor reads the console error and the failed network request simultaneously through Gasoline, identifies that the API returned a 500 causing an undefined .map() call, and adds a null check or error boundary — all in one turn.

How do I connect Cursor to my browser?

Install the Gasoline Chrome extension and add the MCP server config to Cursor’s settings. Gasoline handles the connection between browser and editor over localhost. No accounts, no cloud services, no API keys.

Is Gasoline MCP secure?

Gasoline runs entirely on your machine. The server binds to 127.0.0.1 only and rejects non-localhost connections at the TCP level. It never makes outbound network calls. Sensitive headers (Authorization, Cookie) are stripped from captured network data by default. Request and response body capture is opt-in.

Get Started

npx gasoline-mcp@latest

One command to give Cursor full visibility into your browser. For the complete Cursor integration guide, see the Cursor + Gasoline setup docs.

How to Debug Browser Errors with Claude Code Using MCP

Jan 24, 2025

Brenn Hill

Claude Code is powerful, but it has a blind spot: it can’t see your browser. When your frontend throws an error, you open DevTools, find the relevant console message, copy it, switch to your terminal, paste it, and hope you grabbed enough context. This is slow, lossy, and breaks your flow.

Gasoline MCP is an open-source browser extension + MCP server that streams real-time browser telemetry (console logs, network errors, exceptions, WebSocket events) to AI coding assistants like Claude Code, Cursor, Windsurf, and Zed. It closes the feedback loop between browser and AI — automatically.

The Problem: Manual Copy-Paste Debugging

Without browser access, Claude Code operates on incomplete information. A typical debugging cycle looks like this:

You make a code change
You reload the browser
Something breaks
You open DevTools, scroll through console output
You copy the error, maybe the stack trace
You paste it into Claude Code
Claude asks a follow-up — back to DevTools

You lose context at every step. Stack traces get truncated. Network errors get missed entirely. You never think to check the WebSocket connection that silently dropped.

How Gasoline Solves This

Gasoline connects your browser directly to Claude Code via MCP (Model Context Protocol). Once connected, Claude Code can:

Read console logs — errors, warnings, and info messages with full stack traces
See network failures — failed API calls with status codes, URLs, and timing
Inspect request/response bodies — see exactly what your API returned
Monitor WebSocket events — catch dropped connections and malformed frames
Query the DOM — inspect element state with CSS selectors
Generate Playwright tests — turn a real browser session into a reproducible test

Instead of you copying errors to Claude, Claude pulls what it needs directly.

How Do I Connect Claude Code to My Browser?

Setup takes under 60 seconds.

Step 1: Start the server

npx gasoline-mcp@latest

Single Go binary. No Node.js runtime. No node_modules/. Zero dependencies.

Step 2: Install the Chrome extension

Grab it from the Chrome Web Store (search “Gasoline”). The toolbar icon shows Connected when the server is running.

Step 3: Add the MCP config

Add this to .mcp.json in your project root:

{
  "mcpServers": {
    "gasoline": {
      "command": "npx",
      "args": ["-y", "gasoline-mcp@latest"]
    }
  }
}

Restart Claude Code. The server starts automatically on every session.

Step 4: Ask Claude

Open your web app in Chrome and ask:

“What errors are in the browser?”

Claude Code calls Gasoline’s observe tool and gets back structured data — not a screenshot, not a blob of text, but parsed console entries with timestamps, levels, stack traces, and source locations.

What Browser Data Can Claude Code See Through Gasoline MCP?

Gasoline exposes five composite tools to Claude Code:

Tool	What Claude Can Do
`observe`	Read console errors, network requests, WebSocket events, Web Vitals, page info
`analyze`	Detect performance regressions, audit accessibility, diff sessions
`generate`	Create Playwright tests, reproduction scripts, HAR exports
`configure`	Filter noise, manage log levels, set persistent memory
`query_dom`	Inspect live DOM state using CSS selectors

When Claude calls observe with what: "errors", it gets back every console error from the active tab — structured, timestamped, and ready to act on. When it calls observe with what: "network", it sees every failed HTTP request with status codes, URLs, headers, and optionally full response bodies.

This is not a one-shot snapshot. Gasoline streams continuously. Claude sees errors the moment they happen.

What About Privacy?

Gasoline runs entirely on localhost. The server binary binds to 127.0.0.1 only, rejects non-localhost connections at the TCP level, and never makes outbound network calls. Authorization headers are stripped by default. Request/response body capture is opt-in.

No data leaves your machine. No accounts. No telemetry.

Get Started

npx gasoline-mcp@latest

One command. Zero dependencies. Claude Code sees your browser in under a minute.

Full setup guide

MCP Browser Debugging Tools Compared (2025)

Jan 23, 2025

Brenn Hill

If you’re using an AI coding assistant (Claude Code, Cursor, Windsurf), you’ve probably wished it could see your browser. Several MCP-based tools now make that possible — but they take different approaches.

Here’s a practical breakdown of the options.

The Landscape

Four tools currently give AI assistants browser access via MCP:

Tool	Architecture	Approach
Gasoline	Extension + Go binary	Passive capture
Chrome DevTools MCP	Puppeteer-based server	Active control
BrowserTools MCP	Extension + Node server + MCP server	Passive capture + Lighthouse
Cursor MCP Extension	Extension + MCP server	Passive capture

Passive vs Active: The Fundamental Split

The biggest architectural difference is passive capture vs active control.

Passive Capture (Gasoline, BrowserTools, Cursor MCP)

You browse normally. The extension watches what happens — console logs, network errors, exceptions — and makes that data available to your AI.

Pros:

Zero interference with your browsing
Captures real user behavior
Works on any page you visit

Cons:

Can’t click buttons or navigate programmatically
Can’t take screenshots (traditionally — though some add this)

Active Control (Chrome DevTools MCP)

The tool takes control of a Chrome instance via the Chrome DevTools Protocol (Puppeteer). It can navigate, click, screenshot, and inspect.

Pros:

Full browser automation
Can reproduce issues programmatically
Can take screenshots

Cons:

Requires a separate Chrome instance
Can’t observe your normal browsing
Needs Chrome debug port open

Dependencies Matter

For enterprise environments, the dependency footprint matters:

Tool	Runtime	Install Size	Supply Chain
Gasoline	None (single Go binary)	~10MB	Zero deps
Chrome DevTools MCP	Node.js 22+	~200MB+	Puppeteer + deps
BrowserTools MCP	Node.js	~150MB+	Multiple npm packages
Cursor MCP Extension	Node.js	~100MB+	npm packages

Gasoline’s zero-dependency approach means no node_modules/ folder, no lock file drift, and no supply chain risk. The binary you audit is the binary you run.

Privacy: Where Does Data Go?

Tool	Data Stays Local?	Telemetry	Auth Handling
Gasoline	Yes (127.0.0.1 only)	None	Headers stripped
Chrome DevTools MCP	Depends on config	Unknown	Not stripped
BrowserTools MCP	Yes	Unknown	Not stripped
Cursor MCP Extension	Yes	Unknown	Not stripped

Gasoline is the only tool that architecturally guarantees data locality — the server binary rejects non-localhost connections at the TCP level and never makes outbound network calls.

Performance Impact

Tool	Page Load Impact	Per-Event Overhead	Memory Cap
Gasoline	Zero (deferred init)	< 0.1ms	20MB soft, 50MB hard
Chrome DevTools MCP	N/A (separate instance)	N/A	Unbounded
BrowserTools MCP	Unknown	Unknown	Unknown
Cursor MCP Extension	Unknown	Unknown	Unknown

Gasoline enforces strict SLOs with adaptive sampling for high-frequency events (WebSocket, network bodies).

Feature Comparison

Feature	Gasoline	DevTools MCP	BrowserTools	Cursor MCP
Console capture	Yes	Yes	Yes	Yes
Network errors	Yes	Yes	Yes	Yes
Network bodies	Yes	Partial	No	No
WebSocket monitoring	Yes	No	No	No
DOM queries	Yes	Yes (full control)	No	No
Accessibility audit	Yes (axe-core)	No	Yes (Lighthouse)	No
Test generation	Yes (Playwright)	No	No	No
Screenshots	No	Yes	Yes	No
Browser control	No	Yes	No	No

When to Choose What

Choose Gasoline if:

You want zero dependencies and zero supply chain risk
Enterprise security policies require local-only data handling
You need WebSocket monitoring or network body capture
You want to generate Playwright tests from real sessions
You use any MCP-compatible tool (not just Cursor)

Choose Chrome DevTools MCP if:

You need to automate browser actions
You want screenshot capabilities
You’re building testing/scraping workflows

Choose BrowserTools MCP if:

You specifically need Lighthouse audits
You’re already invested in the Node.js ecosystem

Choose Cursor MCP Extension if:

You only use Cursor
You want the simplest possible setup

How do I get started with Gasoline?

npx gasoline-mcp

One command. No Node.js runtime. No accounts. Full setup guide →