Let your agent drive the browser with MCP

There is a real gap between "my AI can read this page" and "my AI can use this site." A browser extension lives in the page's world: it can scrape the DOM and paste text back, and that is roughly where it stops. Anything stateful — logging in, working through a multi-step form, checking what the network tab said when a request failed — is still your job.

Octoweb closes that gap by running an MCP server inside the browser itself.

The shape of it

MCP client (Claude Desktop / octomind / your script)
        │  HTTP JSON-RPC
        ▼
localhost:3434/mcp   ← inside Octoweb
        │
        ▼
WKWebView — navigate, click, type, read, run JS

The server exposes 29 tools. Navigation and waiting, tab management, page interaction, inspection, and one for agent-rendered UI. A short run looks like this:

news.ycombinator.com

browser_navigatenews.ycombinator.comopened in background

browser_snapshot—41 refs

browser_click@17stable, unobstructed

browser_get_page_content—4.2 kB text

Every one of those calls happened in a tab you were not looking at.

Connecting a client

There is nothing to install or start — the server comes up with the browser. Every client just needs the URL.

Claude Code:

claude mcp add --transport http octoweb http://localhost:3434/mcp

Claude Desktop, Cursor, and anything else that reads a JSON config:

{
	"mcpServers": {
		"octoweb": { "type": "http", "url": "http://localhost:3434/mcp" }
	}
}

octomind, in your config file:

[[mcp.servers]]
name = "octoweb"
type = "http"
url = "http://localhost:3434/mcp"
timeout_seconds = 30

Then /mcp list in the session to confirm the 29 tools arrived.

The rules that make it usable

Handing an agent your browser only works if it does not fight you for the window. Two design rules make the difference:

browser_navigate always opens in the background. New tab, or in place via tab_id — either way it never steals focus.
browser_switch_tab is the only tool that changes what you are looking at. Everything else operates on tabs you are not watching.

So an agent can be working through a ten-page documentation crawl while you read something else in the foreground.

Workspace routing

One server serves every workspace. Each request carries an X-Octoweb-Workspace token that says which workspace it acts on; callers without a token fall through to the first one. Sidebar agent sessions carry their token automatically.

The practical effect: point an agent at a scratch workspace and it gets its own cookie jar, its own history, and its own tabs. Your signed-in session is not just untouched — it is not reachable.

The tools worth knowing

browser_snapshot is the one that changes how agents behave. Instead of dumping HTML, it returns a map of interactive elements with @N refs, and it pierces iframes, shadow DOM, and elements that are only clickable because someone attached a listener. Agents stop guessing at selectors.

browser_click retries until the element is present, stable, and unobstructed — and when it gives up, it reports what was covering the target. That error message alone removes an entire category of flaky agent runs.

browser_fill_form fills several fields and optionally submits in a single call, which keeps a login from becoming six round trips.

browser_console_messages and browser_network_requests give the agent what you would look at yourself: recent console output with JS errors, and recent fetch and XHR activity with statuses and timings. That is the difference between "the button didn't work" and "the POST returned 422 and the console logged a validation error."

The same session is visible from the sidebar, so you can interrupt in plain language while the agent works:

github.com/muvon/octoweb/pull/214

browser_dismiss_overlay handles consent banners. It prefers Reject or Decline and never auto-accepts.

Running a second instance

For test suites, set OCTOWEB_MCP_PORT and OCTOWEB_CONFIG_DIR to get a fully isolated instance:

OCTOWEB_MCP_PORT=3435 OCTOWEB_CONFIG_DIR=/tmp/octoweb-e2e open -a Octoweb
python3 test_mcp.py --mcp-url http://127.0.0.1:3435/mcp

One caveat

The server binds to loopback, but any local client that can reach it can read page content and browsing history. Treat it like any other local development port: fine on your laptop, worth thinking about on a shared machine.

The full tool reference lists all 29.