-
-
Notifications
You must be signed in to change notification settings - Fork 117
Expand file tree
/
Copy pathindex.html
More file actions
140 lines (120 loc) · 34.7 KB
/
Copy pathindex.html
File metadata and controls
140 lines (120 loc) · 34.7 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
<!doctype html>
<html lang="en" data-theme="dark">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Use WebBrain with MCP — WebBrain User Guide</title>
<meta name="description" content="Connect Codex, Claude Code, Hermes Agent, OpenClaw, Cursor, OpenCode, or another local stdio MCP client to WebBrain in your real signed-in Chromium browser, with verified setup commands and practical use cases.">
<link rel="canonical" href="https://webbrain.one/docs/mcp/">
<link rel="alternate" hreflang="en" href="https://webbrain.one/docs/mcp/">
<link rel="alternate" hreflang="x-default" href="https://webbrain.one/docs/mcp/">
<link rel="icon" href="/favicon.png">
<script>try{document.documentElement.dataset.theme=localStorage.getItem('webbrain-theme')||'dark'}catch(_){}</script>
<link rel="stylesheet" href="/docs/assets/docs.css?v=20260809">
<!-- Plausible analytics: start -->
<!-- Privacy-friendly analytics by Plausible -->
<script async src="https://plausible.io/js/pa-yWGfwxkkKSVs-eTuaKYpy.js"></script>
<script>
window.plausible=window.plausible||function(){(plausible.q=plausible.q||[]).push(arguments)},plausible.init=plausible.init||function(i){plausible.o=i||{}};
plausible.init()
</script>
<!-- Plausible analytics: end -->
</head>
<body class="doc-page">
<a class="skip-link" href="#main">Skip to content</a>
<header class="site-header"><div class="header-inner"><a class="brand" href="/"><img src="/logo-github.png" alt=""><span>WebBrain</span><span class="brand-docs">User guide</span></a><nav class="top-nav" aria-label="Primary"><a href="/">Home</a><a href="/docs/" aria-current="page">Docs</a><a href="/blog/">Blog</a><a href="https://github.com/webbrain-one/webbrain">GitHub</a></nav><div class="header-tools"><button class="icon-button" type="button" data-theme-toggle aria-label="Use light theme">☀</button><button class="sidebar-toggle" type="button" data-sidebar-toggle aria-expanded="false" aria-label="Open documentation menu">☰</button></div></div></header>
<div class="docs-shell">
<aside class="docs-sidebar" aria-label="Documentation"><div class="sidebar-group"><div class="sidebar-label">Start here</div><nav><a href="/docs/">Overview</a><a href="/docs/faq/">FAQ</a></nav></div><div class="sidebar-group"><div class="sidebar-label">Use WebBrain</div><nav><a href="/docs/settings/">Settings, explained</a><a href="/docs/providers/">Providers & models</a><a href="/docs/easy-cli-proxy/">Subscription proxy</a><a href="/docs/safety/">Modes, safety & privacy</a><a href="/docs/apocalypse-mode/">Apocalypse Mode</a><a href="/docs/formats/">Exports & workflows</a><a href="/docs/mcp/" aria-current="page">MCP server</a><a href="/docs/lm-studio/">LM Studio plugin</a><a href="/docs/ollama/">Ollama</a></nav></div><div class="sidebar-group"><div class="sidebar-label">MCP source</div><nav><a href="https://github.com/webbrain-one/webbrain/tree/main/mcp-server">Server package ↗</a><a href="https://www.npmjs.com/package/@webbrain/mcp-server">npm package ↗</a><a href="/blog/mcp-server-introduction">Launch article ↗</a></nav></div><div class="sidebar-group"><div class="sidebar-label">Community</div><nav><a href="https://discord.gg/cgC325ssfw">Discord Support</a></nav></div></aside>
<main class="doc-main" id="main">
<div class="breadcrumb"><a href="/docs/">Docs</a> / MCP server</div>
<section class="doc-hero"><div class="eyebrow">Real session, task-level control</div><h1>Let your coding or personal agent use the browser you are already signed into.</h1><p class="lede">WebBrain MCP connects Codex, Claude Code, Hermes Agent, OpenClaw, Cursor, OpenCode, and other local stdio MCP clients to your real Chromium profile. After the one-time setup, just describe the browser job in normal language. Your agent chooses and calls the appropriate WebBrain tool; WebBrain performs the goal inside the browser with the same modes, origin permissions, and visible stop controls as the side panel.</p><div class="callout tip"><strong class="callout-title">You do not type MCP function calls</strong><p>Say “Use WebBrain to summarize the dashboard already open in my browser” or “Use WebBrain in Act mode to update this form.” Your MCP client translates that request into the tool call and returns the result in the same conversation. Function-shaped examples later in this guide show what happens under the hood and are mainly for debugging or client builders.</p></div><div class="callout warning"><strong class="callout-title">Chromium only</strong><p>The bridge requires the extension’s offscreen document, so use Chrome, Edge, Brave, Opera, or Vivaldi. The Firefox extension remains fully usable on its own, but it cannot connect to this MCP server.</p></div></section>
<section class="doc-section" id="architecture"><div class="eyebrow">The complete path</div><h2>What starts where</h2><p>Your MCP client launches the npm package as a local child process over stdio. That process listens only on <code>127.0.0.1:17374</code>. The extension dials out to it, then carries each task through WebBrain’s agent loop in the selected browser tab.</p><div class="bridge-map" role="img" aria-label="Local agent over MCP stdio to local WebBrain server over loopback WebSocket to the signed-in Chromium extension"><div class="bridge-node"><strong>Codex, Claude Code, Hermes, OpenClaw, Cursor, OpenCode</strong><span>MCP client · owns the child process</span></div><div class="bridge-arrow" aria-hidden="true">→</div><div class="bridge-node local"><strong>@webbrain/mcp-server</strong><span>stdio · 127.0.0.1:17374</span></div><div class="bridge-arrow" aria-hidden="true">→</div><div class="bridge-node"><strong>WebBrain in your browser</strong><span>signed-in tabs · permission gate</span></div></div><p>The server is not a second browser and does not copy cookies. It is a local handoff point between the MCP client and the extension. The browser profile—and therefore the authenticated session—never moves.</p><div class="callout warning"><strong class="callout-title">The agent and browser must run on the same computer</strong><p><code>127.0.0.1</code> always means the machine running the MCP server. A Codex cloud task, remote SSH or dev-container session, hosted OpenClaw runtime, or remote Hermes gateway cannot reach the extension in your laptop browser. Run the MCP client locally instead. Do not expose or tunnel port <code>17374</code>; it can control signed-in tabs and is intentionally loopback-only.</p></div></section>
<section class="doc-section" id="requirements"><h2>Before you connect</h2><div class="table-wrap"><table><thead><tr><th>Requirement</th><th>What to check</th></tr></thead><tbody><tr><td>Chromium browser</td><td>Chrome, Edge, Brave, Opera, or Vivaldi with the current WebBrain extension installed.</td></tr><tr><td>Node.js</td><td>Node 20 or newer. <code>npx</code> downloads and launches the published <code>@webbrain/mcp-server</code> package.</td></tr><tr><td>Local MCP client</td><td>Codex, Claude Code, Hermes Agent, OpenClaw, Cursor, OpenCode, or another client with local stdio support, running on the same computer as Chromium.</td></tr><tr><td>One free local port</td><td><code>17374</code> must not already be held by another WebBrain MCP process.</td></tr><tr><td>An active WebBrain provider</td><td>The extension still needs a configured WebBrain Compass, local, or API-backed model to perform the delegated task.</td></tr></tbody></table></div></section>
<section class="doc-section" id="register"><div class="eyebrow">Step 1 · one time only</div><h2>Register WebBrain with your agent</h2><p>Choose the client that will run on the same computer as Chromium. These commands configure the integration; they are not how you request browser work. After registration, the client starts the stdio server for you and you continue chatting normally. Use only one active WebBrain MCP client at a time, because one process must own port <code>17374</code>.</p><div class="table-wrap"><table><thead><tr><th>Client</th><th>Where WebBrain is registered</th><th>Connection check</th></tr></thead><tbody><tr><td><a href="#codex">Codex</a></td><td>Shared Codex <code>config.toml</code></td><td><code>codex mcp list</code> and <code>/mcp</code></td></tr><tr><td><a href="#claude-code">Claude Code</a></td><td>User, project, or local scope</td><td><code>claude mcp get webbrain</code> and <code>/mcp</code></td></tr><tr><td><a href="#hermes-agent">Hermes Agent</a></td><td><code>~/.hermes/config.yaml</code></td><td><code>hermes mcp test webbrain</code></td></tr><tr><td><a href="#openclaw">OpenClaw</a></td><td>Outbound <code>mcp.servers</code> registry</td><td><code>openclaw mcp doctor webbrain --probe</code></td></tr><tr><td><a href="#cursor">Cursor</a></td><td>Global or project <code>mcp.json</code></td><td>Settings → MCP or <code>agent mcp list</code></td></tr><tr><td><a href="#opencode">OpenCode v2</a></td><td>Global or project <code>opencode.json(c)</code></td><td>Start a fresh local session and inspect its MCP tools</td></tr></tbody></table></div><h3 id="codex">Codex app, CLI, or IDE extension</h3><pre class="code-block"><code>codex mcp add webbrain -- npx -y @webbrain/mcp-server
codex mcp list</code></pre><p>Codex stores MCP servers in <code>~/.codex/config.toml</code>; the ChatGPT desktop app, Codex CLI, and Codex IDE extension on the same host share that configuration. For long browser tasks, give WebBrain more than Codex’s default per-tool budget:</p><pre class="code-block"><code>[mcp_servers.webbrain]
command = "npx"
args = ["-y", "@webbrain/mcp-server"]
tool_timeout_sec = 360</code></pre><p>Restart the app or IDE extension after changing the file. Use <code>/mcp</code> inside a local Codex session to inspect the connected server. This local configuration is not available to Codex cloud tasks or ChatGPT on the web. See the <a href="https://learn.chatgpt.com/docs/extend/mcp">official Codex MCP guide</a> for the current shared-host configuration and supported options.</p><p><strong>Example:</strong> “Use WebBrain in Ask mode to read the staging error page already open in Chrome, then compare what it shows with this repository and identify the likely code path. Do not change the page.”</p><h3 id="claude-code">Claude Code</h3><pre class="code-block"><code>claude mcp add --transport stdio --scope user webbrain -- \
npx -y @webbrain/mcp-server
claude mcp get webbrain</code></pre><p><code>--scope user</code> makes WebBrain available in every local project. Use <code>--scope project</code> instead when your team should share a checked-in <code>.mcp.json</code>; omit the scope for Claude Code’s project-local default. In a session, <code>/mcp</code> shows connection status. The option ordering and stdio separator above follow the current <a href="https://code.claude.com/docs/en/mcp">Claude Code MCP guide</a>.</p><p><strong>Example:</strong> “Use WebBrain to read the CI dashboard already open in my browser, summarize the failing jobs, then inspect this branch for the most likely causes. Do not rerun jobs or change the dashboard.”</p><h3 id="hermes-agent">Hermes Agent</h3><pre class="code-block"><code>hermes mcp add webbrain \
--command npx \
--args -y @webbrain/mcp-server
hermes mcp test webbrain</code></pre><p>Keep <code>--args</code> last: current Hermes treats the remainder of the command as stdio arguments. Hermes saves the server under <code>mcp_servers</code> in <code>~/.hermes/config.yaml</code>, discovers its tools when a session starts, and prefixes their internal names with <code>mcp_webbrain_</code>. You still ask in natural language. The equivalent manual configuration is:</p><pre class="code-block"><code>mcp_servers:
webbrain:
command: "npx"
args: ["-y", "@webbrain/mcp-server"]
timeout: 360</code></pre><p>Start <code>hermes chat</code> after adding the server. Use <code>/reload-mcp</code> if you edit the YAML during a running session. Do not use <code>hermes mcp serve</code> here; that exposes Hermes’s messaging bridge to other clients, the opposite direction. See the current <a href="https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp">Hermes MCP guide</a>.</p><p><strong>Example:</strong> “Use WebBrain to read the support dashboard already open in Chromium and summarize unresolved urgent tickets here. Do not change ticket state.”</p><h3 id="cursor">Cursor</h3><p>Add a local stdio server in Cursor’s MCP settings, <code>~/.cursor/mcp.json</code> for all projects, or <code>.cursor/mcp.json</code> in one project. The shape follows <a href="https://cursor.com/docs/mcp">Cursor’s current local MCP format</a>:</p><pre class="code-block"><code>{
"mcpServers": {
"webbrain": {
"command": "npx",
"args": ["-y", "@webbrain/mcp-server"]
}
}
}</code></pre><p>Restart Cursor or reload MCP servers, then inspect Settings → MCP. Cursor’s CLI can check the same configuration with <code>agent mcp list</code>. A project file travels with the repository; the global file is private and follows you across projects.</p><p><strong>Example:</strong> “Use WebBrain to read the local app preview open in Chrome, list every visible layout or validation problem, then fix the corresponding files in this project. Do not submit any forms.”</p><h3 id="opencode">OpenCode v2</h3><p>Add this entry to the global <code>~/.config/opencode/opencode.json(c)</code> file or a project <code>opencode.json(c)</code>. Current OpenCode v2 nests named servers under <code>mcp.servers</code>:</p><pre class="code-block"><code>{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"servers": {
"webbrain": {
"type": "local",
"command": ["npx", "-y", "@webbrain/mcp-server"]
}
}
}
}</code></pre><p>Start a fresh local OpenCode session after saving the file. MCP tools are available to agents automatically; name WebBrain in the prompt when you want to make the routing explicit. See the current <a href="https://opencode.ai/v2/docs/mcp-servers">OpenCode v2 MCP guide</a> and <a href="https://opencode.ai/v2/docs/config">configuration locations</a>.</p><p><strong>Example:</strong> “Use WebBrain in Ask mode to inspect the documentation preview open in Chromium, compare it with this project’s source, and suggest the smallest fix. Do not change the page.”</p><h3 id="openclaw">OpenClaw</h3><p>Register WebBrain in OpenClaw’s outbound MCP registry. Do not use <code>openclaw mcp serve</code> for this integration: that command makes OpenClaw itself act as a server, which is the opposite direction.</p><pre class="code-block"><code>openclaw mcp add webbrain \
--command npx \
--arg -y \
--arg @webbrain/mcp-server \
--timeout 360
openclaw mcp doctor webbrain --probe</code></pre><p><code>mcp add</code> probes the stdio server before saving it; <code>doctor --probe</code> performs a fresh launch and tool-discovery check. <code>status --verbose</code> only inspects the saved definition. Normal <code>coding</code> and <code>messaging</code> profiles include configured MCP servers; <code>minimal</code>, an explicit <code>bundle-mcp</code> deny, or a sandbox policy can hide them. See the current <a href="https://docs.openclaw.ai/cli/mcp">OpenClaw MCP guide</a>.</p><p>Whenever OpenClaw invokes WebBrain, the OpenClaw runtime, Chromium, WebBrain extension, and WebBrain provider must all be running on this computer.</p><p><strong>Example:</strong> “Use WebBrain to read the operations dashboard already open in Chromium and post a read-only summary of today’s warnings in this conversation.”</p><h3>Any other local stdio client</h3><p>Configure the executable as <code>npx</code> and the argument array as <code>["-y", "@webbrain/mcp-server"]</code>. The client must own the child process, preserve stdout for MCP messages, and run on the same computer as the browser.</p><h3>Run it manually</h3><p>Manual launch is useful for diagnosing the listener, but not required during normal MCP use:</p><pre class="code-block"><code>npx -y @webbrain/mcp-server</code></pre><p>Leave that terminal open. Closing it closes the bridge listener. From a source checkout, run <code>npm install</code>, <code>npm run build</code>, then <code>npm start</code> inside <code>mcp-server/</code>.</p></section>
<section class="doc-section" id="browser"><div class="eyebrow">Step 2</div><h2>Point WebBrain at the local listener</h2><ol class="step-list"><li><strong>Start or restart your MCP client.</strong> Its WebBrain server must be running before the extension can connect.</li><li><strong>Open WebBrain Settings.</strong> Go to <strong>General → Advanced → MCP</strong>.</li><li><strong>Set the exact URL.</strong> Enter <code>ws://127.0.0.1:17374/extension</code>.</li><li><strong>Enable MCP.</strong> The status should move from connecting to connected.</li><li><strong>Verify end to end.</strong> Ask the MCP client to call <code>webbrain_connection</code>. “Connected” proves the client, local server, WebSocket listener, and extension handshake are all present.</li></ol><div class="callout"><strong class="callout-title">One bridge destination at a time</strong><p>The extension holds one outbound bridge socket: WebBrain Cloud on <code>17373</code>, this MCP server on <code>17374</code>, or the LM Studio plugin on <code>17375</code>. Changing the URL switches the destination; it does not multiplex them.</p></div></section>
<section class="doc-section" id="first-task"><div class="eyebrow">Step 3 · just ask</div><h2>Describe the browser job in natural language</h2><p>In Codex, Claude Code, Hermes Agent, OpenClaw, Cursor, or OpenCode, write the request the same way you would give it to a teammate. Naming WebBrain makes your intent unambiguous; include the open page, desired outcome, scope, output shape, and whether changes are allowed.</p><h3>Read something without changing the page</h3><blockquote>Use WebBrain to read the Stripe dashboard already open in my browser. List failed payments from the last seven days with customer, amount, currency, date, and failure reason. Do not change anything.</blockquote><h3>Combine browser evidence with a codebase</h3><blockquote>Use WebBrain in Ask mode to inspect the staging error already open in Chromium. Then inspect this repository, connect the visible error to the most likely implementation, and propose a fix. Do not change the browser page.</blockquote><h3>Return predictable JSON</h3><blockquote>Use WebBrain to extract every overdue invoice from the dashboard already open in my browser. Return JSON with customer, amount, currency, due date, and invoice URL. Do not change anything.</blockquote><h3>Report back through a personal agent</h3><blockquote>Use WebBrain to read the support dashboard already open on this computer and summarize urgent unresolved tickets in this conversation. Keep the run read-only.</blockquote><h3>Interact with the page</h3><blockquote>Use WebBrain in Act mode to open the customer record already visible in my browser and update the company name to Acme Europe. Stop before any final submit or confirmation.</blockquote><p>The agent chooses <code>webbrain_run</code> for general reading or interaction and <code>webbrain_extract</code> when you request structured data. It supplies the arguments, monitors the run, and presents WebBrain’s result back in the conversation. Ask mode can read and extract; it cannot click, type, navigate, or submit. Act mode can interact, subject to WebBrain’s normal browser-side permissions.</p><div class="callout"><strong class="callout-title">Under the hood — you do not enter this</strong><p>For the first prompt above, the client will make a call similar to the following. This representation is useful when building or debugging an MCP client, but ordinary users can ignore it.</p></div><pre class="code-block"><code>webbrain_run(
task: "read the open Stripe dashboard and list failed payments from the last 7 days with customer, amount, currency, date, and failure reason",
mode: "ask"
)</code></pre><p>For a task that must interact, explicitly say “use WebBrain in Act mode” and keep the browser visible. WebBrain will apply its normal capability-by-origin approval prompts.</p></section>
<section class="doc-section" id="tools"><div class="eyebrow">Six tools, one trust boundary</div><h2>What your MCP client uses for you</h2><p>You normally choose an outcome, not a tool. Your MCP client reads these descriptions, selects the appropriate tool, fills its inputs from your request, and handles follow-up calls. This reference is here so you can understand or debug that behavior.</p><div class="table-wrap"><table><thead><tr><th>Tool</th><th>Use it for</th><th>Important inputs</th></tr></thead><tbody><tr><td><code>webbrain_run</code></td><td>Any browser goal, read-only or interactive.</td><td><code>task</code>, <code>mode</code>, optional <code>tab_id</code>, <code>wait</code>, <code>timeout_seconds</code>, and Act-only <code>allow_api_mutations</code>.</td></tr><tr><td><code>webbrain_extract</code></td><td>Predictable JSON from authenticated page data. Always Ask mode.</td><td><code>task</code>, <code>output_schema</code>, optional <code>tab_id</code>, <code>wait</code>, and <code>timeout_seconds</code>.</td></tr><tr><td><code>webbrain_status</code></td><td>Poll one background run or list all known runs.</td><td>Optional <code>run_id</code>. Omit it to list runs.</td></tr><tr><td><code>webbrain_respond</code></td><td>Pass the human’s answer back to a paused run.</td><td><code>run_id</code>, <code>clarify_id</code>, <code>answer</code>, optional <code>timeout_seconds</code>.</td></tr><tr><td><code>webbrain_abort</code></td><td>Stop a run that is wrong or no longer needed.</td><td><code>run_id</code>. It does not undo actions already taken.</td></tr><tr><td><code>webbrain_connection</code></td><td>Check the extension handshake and get a targeted fix when disconnected.</td><td>No inputs.</td></tr></tbody></table></div><div class="callout tip"><strong class="callout-title">Why there is no MCP click or type tool</strong><p>WebBrain’s permission checks live in the extension agent loop. Exposing low-level primitives directly over MCP would sit below that boundary. These tools delegate a goal through the normal loop, preserving in-browser review while using fewer round trips and tokens.</p></div></section>
<section class="doc-section" id="structured"><h2>Ask for structured JSON</h2><p>In normal use, say what to extract and name the fields you want: “Use WebBrain to extract every overdue invoice from the open dashboard as JSON with customer, amount, currency, due date, and invoice URL.” A capable MCP client can translate those fields into the required schema and call <code>webbrain_extract</code> for you.</p><p>The function-shaped example below shows the equivalent tool call for client builders and debugging. Describe the selection logic in <code>task</code>; describe only the output shape in <code>output_schema</code>.</p><pre class="code-block"><code>webbrain_extract(
task: "extract every overdue invoice visible in this account; preserve the displayed currency and use ISO dates where the page provides a full date",
output_schema: {
type: "object",
properties: {
invoices: {
type: "array",
items: {
type: "object",
properties: {
customer: { type: "string" },
amount: { type: "number" },
currency: { type: "string" },
due_date: { type: "string" },
invoice_url: { type: "string" }
},
required: ["customer", "amount", "currency", "due_date"]
}
}
},
required: ["invoices"]
}
)</code></pre><ul><li>Use an object root with explicit <code>properties</code> and <code>required</code> fields.</li><li>Ask for the narrowest data you need. A schema does not grant access to data that is not visible to the browser session.</li><li>The tool is read-only, but the page text and result still travel to whichever LLM provider WebBrain is configured to use.</li><li>If the result is too large for the run’s persisted snapshot, status can report that the stored result was truncated. Narrow the request and rerun.</li></ul></section>
<section class="doc-section" id="lifecycle"><h2>Understand the run lifecycle</h2><p>Most MCP clients manage this lifecycle for you: they wait for the result, show WebBrain’s clarification question when human input is needed, and continue with your answer. The explicit calls below are useful for client builders, troubleshooting, or deliberately prompting the client to start a long task in the background.</p><p>A foreground call waits by default. For long work, the client can set <code>wait: false</code> and poll with <code>webbrain_status</code>.</p><div class="status-strip" aria-label="WebBrain MCP run statuses"><div class="status-item"><code>running</code><span>Work continues in the browser</span></div><div class="status-item waiting"><code>needs_user_input</code><span>Relay the question to the human</span></div><div class="status-item done"><code>completed</code><span>Result is ready</span></div><div class="status-item"><code>failed</code><span>Read the error and evidence</span></div><div class="status-item"><code>aborted</code><span>Stopped; earlier actions remain</span></div></div><pre class="code-block"><code># Tool-level reference
# Start without waiting
webbrain_run(task: "compare the invoices across all visible pages", mode: "ask", wait: false)
# Poll the returned ID
webbrain_status(run_id: "mcp_…")</code></pre><p>A WebBrain run timeout returns control to the MCP client but deliberately does not abort the browser task. Poll the returned <code>run_id</code>. This prevents a timeout from silently killing a task after it may already have taken a consequential action.</p><h3>When WebBrain asks a question</h3><p>A paused snapshot includes both a human-readable question and a <code>clarify_id</code>. Show the question to the user. Send their answer verbatim; do not infer it.</p><pre class="code-block"><code>webbrain_respond(
run_id: "mcp_…",
clarify_id: "clarify_…",
answer: "Use the Acme EU account."
)</code></pre></section>
<section class="doc-section" id="modes"><h2>Choose the smallest authority</h2><div class="table-wrap"><table><thead><tr><th>Choice</th><th>What it allows</th><th>Use when</th></tr></thead><tbody><tr><td><code>mode: "ask"</code></td><td>Reading, summarizing, comparing, and extracting. No page interaction.</td><td>You only need information. This is the default.</td></tr><tr><td><code>mode: "act"</code></td><td>Navigation, clicking, typing, downloading, and form interaction through WebBrain’s permission gate.</td><td>The outcome requires visible browser actions.</td></tr><tr><td><code>allow_api_mutations: true</code></td><td>Allows an Act run to use mutating HTTP requests when the UI path is unsuitable.</td><td>Rare, explicit exceptions. It is rejected in Ask mode and should stay off by default.</td></tr></tbody></table></div><p>MCP-client approval and WebBrain approval are separate layers. Your client may ask before it invokes <code>webbrain_run</code>; WebBrain may then ask before a consequential action on a particular origin. One approval does not replace the other.</p></section>
<section class="doc-section" id="security"><h2>Security boundaries you should keep</h2><ul><li><strong>Keep the listener local.</strong> It binds to <code>127.0.0.1</code>. Do not forward port <code>17374</code>, publish it through a container bridge, or proxy it onto a network.</li><li><strong>Loopback is not authentication.</strong> The extension sends an identifying handshake but no shared secret. A process already running as your local user could attempt to impersonate the extension or server. Treat local code and MCP packages as trusted software.</li><li><strong>Use Ask first.</strong> Read-only work is easier to verify and has a smaller blast radius.</li><li><strong>Keep the browser visible for Act.</strong> You can stop the run in the side panel, and unexpected navigation or typing should be treated as a reason to stop.</li><li><strong>Remember the provider boundary.</strong> The MCP bridge stays local, but page content is sent to the model provider configured in WebBrain. Use a local model when the content must remain on-device.</li><li><strong>Do not mistake a timeout for a rollback.</strong> Aborting stops future steps; it cannot undo a sent email, submitted form, purchase, or other completed action.</li></ul><p>For the complete design, see the <a href="https://github.com/webbrain-one/webbrain/blob/main/docs/security-model.md">security model</a>, <a href="https://github.com/webbrain-one/webbrain/blob/main/docs/privacy-and-data-flow.md">privacy and data flow</a>, and <a href="/docs/safety/">modes, safety, and privacy guide</a>.</p></section>
<section class="doc-section" id="troubleshooting"><h2>Troubleshooting by symptom</h2><div class="table-wrap"><table><thead><tr><th>Symptom</th><th>What it usually means</th><th>Fix</th></tr></thead><tbody><tr><td><strong>Connection error: WebSocket error</strong></td><td>No process is listening at the configured URL.</td><td>Start or restart the MCP client, confirm port <code>17374</code>, and leave the server process running.</td></tr><tr><td><code>webbrain_connection</code> says not connected</td><td>The local server exists, but the extension has not completed its handshake.</td><td>Use a Chromium browser, enable MCP, and set the exact <code>/extension</code> URL.</td></tr><tr><td><code>EADDRINUSE</code> or the server exits immediately</td><td>Another MCP client or manual server already owns port <code>17374</code>.</td><td>Stop the other process. Only one WebBrain MCP server can own the default port at a time.</td></tr><tr><td>The MCP tools do not appear</td><td>The client has not reloaded its configuration or the npm process failed to start.</td><td>Restart the client, inspect its MCP server list/log, and confirm Node 20+ plus npm access.</td></tr><tr><td>The tool returns <code>running</code></td><td>The server or client wait budget expired; the browser run was intentionally left alive.</td><td>Poll <code>webbrain_status</code> with the returned ID, or start future long tasks with <code>wait: false</code>.</td></tr><tr><td>The run says <code>needs_user_input</code></td><td>WebBrain needs a human decision before it can continue.</td><td>Relay the exact question, then call <code>webbrain_respond</code> with the matching IDs.</td></tr><tr><td>Firefox never connects</td><td>Firefox has no offscreen-document bridge runtime.</td><td>Use Chrome, Edge, Brave, Opera, or Vivaldi for MCP. Firefox remains supported for direct side-panel use.</td></tr><tr><td>WebBrain Cloud or LM Studio disconnected</td><td>The MCP URL replaced the extension’s single bridge destination.</td><td>Switch the MCP URL back to port <code>17373</code> or <code>17375</code> when you are finished.</td></tr></tbody></table></div><p>Check the listener directly:</p><pre class="code-block"><code>lsof -nP -iTCP:17374 -sTCP:LISTEN</code></pre><p>No output means nothing is listening. If a PID appears and you did not expect it, identify the process before stopping it.</p></section>
<section class="doc-section" id="configuration"><h2>Environment configuration</h2><div class="table-wrap"><table><thead><tr><th>Variable</th><th>Default</th><th>Meaning</th></tr></thead><tbody><tr><td><code>WEBBRAIN_BRIDGE_PORT</code></td><td><code>17374</code></td><td>Loopback port the extension connects to.</td></tr><tr><td><code>WEBBRAIN_BRIDGE_PATH</code></td><td><code>/extension</code></td><td>WebSocket path; it must match Settings.</td></tr><tr><td><code>WEBBRAIN_COMMAND_TIMEOUT_MS</code></td><td><code>30000</code></td><td>Budget for one bridge command and reply.</td></tr><tr><td><code>WEBBRAIN_RUN_TIMEOUT_MS</code></td><td><code>300000</code></td><td>Default wait ceiling for a run or extraction.</td></tr><tr><td><code>WEBBRAIN_POLL_INTERVAL_MS</code></td><td><code>1000</code></td><td>How often the server polls a running task.</td></tr></tbody></table></div><p>For a stdio client, set environment variables in that client’s MCP configuration. If you change the port or path, update the MCP URL in WebBrain Settings to match exactly.</p></section>
<section class="doc-section" id="lm-studio"><div class="eyebrow">Related integration</div><h2>Using LM Studio instead?</h2><p>LM Studio uses the separate <strong>WebBrain Web Tools plugin</strong>, not this MCP package. Its <code>fetch_url</code> and <code>research_url</code> tools can read public pages without the browser extension; its browser tools can delegate a goal to your signed-in Chromium session through port <code>17375</code>.</p><div class="callout"><strong class="callout-title">Choose one bridge destination</strong><p>Do not register <code>@webbrain/mcp-server</code> inside LM Studio just to use the published plugin. Follow the <a href="/docs/lm-studio/">LM Studio plugin guide</a>, then switch the extension’s MCP URL from MCP port <code>17374</code> to plugin port <code>17375</code> when you want that integration.</p></div></section>
<section class="doc-section" id="limits"><h2>What this server deliberately does not do</h2><ul><li>It does not launch a headless browser or create a fresh browser profile.</li><li>It does not work through the Firefox build.</li><li>It does not export cookies, credentials, or session storage.</li><li>It does not expose WebBrain’s roughly fifty click, type, frame, screenshot, network, and DOM primitives directly to the MCP client.</li><li>It does not make the bridge safe to expose remotely.</li><li>It does not remove the need for a configured model inside WebBrain.</li></ul><p>If you need deterministic low-level browser automation in an isolated profile, a Playwright-style MCP server may fit better. Use WebBrain MCP when the defining requirement is your existing signed-in browser session plus WebBrain’s in-browser safety model.</p></section>
<nav class="next-links" aria-label="Next guides"><a href="/docs/safety/"><span>Related</span>← Modes, safety & privacy</a><a href="/docs/lm-studio/"><span>Another local integration</span>LM Studio plugin guide →</a></nav>
</main>
<aside class="on-this-page" aria-label="On this page"><h2>On this page</h2><a href="#architecture">Architecture</a><a href="#requirements">Requirements</a><a href="#register">Client integrations</a><a href="#browser">Connect the browser</a><a href="#first-task">Use cases</a><a href="#tools">Tool reference</a><a href="#structured">Structured extraction</a><a href="#lifecycle">Run lifecycle</a><a href="#modes">Authority</a><a href="#security">Security</a><a href="#troubleshooting">Troubleshooting</a><a href="#configuration">Configuration</a><a href="#lm-studio">LM Studio</a><a href="#limits">Deliberate limits</a></aside>
</div>
<footer class="site-footer"><div class="footer-inner"><span>WebBrain user guide</span><div class="footer-links"><a href="/privacy">Privacy</a><a href="https://github.com/webbrain-one/webbrain/issues">Report an issue</a></div></div></footer>
<script src="/docs/assets/docs.js?v=20260809"></script>
</body>
</html>