-
-
Notifications
You must be signed in to change notification settings - Fork 97
Expand file tree
/
Copy pathindex.html
More file actions
126 lines (106 loc) · 28.5 KB
/
Copy pathindex.html
File metadata and controls
126 lines (106 loc) · 28.5 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
<!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, Cursor, OpenClaw, OpenCode, or another stdio MCP client to WebBrain in your real signed-in Chromium browser, then run, extract, monitor, clarify, and stop browser tasks safely.">
<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/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 agent use the browser you are already signed into.</h1><p class="lede">WebBrain MCP connects Codex, Claude Code, Cursor, OpenClaw, OpenCode, and other stdio MCP clients to your real Chromium profile. After the one-time setup, just describe the browser job in normal language. Your coding 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="Coding 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, Cursor, OpenClaw, 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></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 package.</td></tr><tr><td>MCP client</td><td>A client that supports local stdio servers, such as Codex, Claude Code, Cursor, OpenClaw, or OpenCode.</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 Cloud, 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 the server with your MCP client</h2><p>Use one of these client-specific configurations once. These are installation commands, not the way you request browser work. After registration, the client launches the server for you and you continue chatting normally; do not also keep a manual copy running on the same port.</p><h3>Codex app, CLI, or IDE extension</h3><pre class="code-block"><code>codex mcp add webbrain -- npx -y @webbrain/mcp-server</code></pre><p>Codex stores MCP servers in <code>~/.codex/config.toml</code>; the app, CLI, and IDE extension on the same Codex host share that configuration. For long browser tasks, open that file and give the tool more than Codex’s default per-call 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. In the CLI, run <code>codex mcp list</code> to confirm the entry and use <code>/mcp</code> inside a Codex session to inspect connected servers. See the <a href="https://learn.chatgpt.com/docs/extend/mcp">official Codex MCP guide</a> for the shared host configuration and all supported options.</p><h3>Claude Code</h3><pre class="code-block"><code>claude mcp add --transport stdio webbrain -- npx -y @webbrain/mcp-server</code></pre><p>The explicit transport matches the current <a href="https://code.claude.com/docs/en/mcp">Claude Code MCP configuration</a>. Run <code>claude mcp list</code> after adding it to inspect server health.</p><h3>Cursor</h3><p>Add a local stdio server in Cursor’s MCP settings, or place this in the MCP JSON file Cursor uses. The shape follows <a href="https://cursor.com/docs/context/mcp">Cursor’s local MCP server format</a>:</p><pre class="code-block"><code>{
"mcpServers": {
"webbrain": {
"command": "npx",
"args": ["-y", "@webbrain/mcp-server"]
}
}
}</code></pre><h3>OpenCode</h3><p>Add this entry to <code>~/.config/opencode/opencode.json</code>, using OpenCode’s <a href="https://opencode.ai/docs/mcp-servers/">local MCP server format</a>:</p><pre class="code-block"><code>{
"mcp": {
"webbrain": {
"type": "local",
"command": ["npx", "-y", "@webbrain/mcp-server"]
}
}
}</code></pre><h3>OpenClaw</h3><p>Register WebBrain as an outbound MCP server in OpenClaw. 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</code></pre><p><code>mcp add</code> probes the stdio server before saving it. Run <code>openclaw mcp status --verbose</code> to inspect the saved definition. Normal <code>coding</code> and <code>messaging</code> tool profiles include configured MCP servers; a <code>minimal</code> profile, an explicit <code>bundle-mcp</code> deny, or a sandbox tool policy can hide them. See the <a href="https://docs.openclaw.ai/cli/mcp">OpenClaw MCP guide</a> for the current registry and policy details.</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 → Cloud bridge</strong>.</li><li><strong>Set the exact URL.</strong> Enter <code>ws://127.0.0.1:17374/extension</code>.</li><li><strong>Enable Cloud bridge.</strong> The status should move from connecting to connected. The name is historical: this destination is local.</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, Cursor, OpenClaw, or OpenCode, write the request the same way you would give it to a teammate. Naming WebBrain makes your intent unambiguous; include the page, desired outcome, scope, 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>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>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 coding 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 Cloud bridge, 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 Cloud bridge 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 Cloud bridge 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 Cloud bridge 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">Register a client</a><a href="#browser">Connect the browser</a><a href="#first-task">First task</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>