Let your coding agent use the browser you are already signed into.

What starts where

Your MCP client launches the npm package as a local child process over stdio. That process listens only on 127.0.0.1:17374. The extension dials out to it, then carries each task through WebBrain’s agent loop in the selected browser tab.

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.

Before you connect

Register the server with your MCP client

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.

Codex app, CLI, or IDE extension

codex mcp add webbrain -- npx -y @webbrain/mcp-server

Codex stores MCP servers in ~/.codex/config.toml; 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:

[mcp_servers.webbrain]
command = "npx"
args = ["-y", "@webbrain/mcp-server"]
tool_timeout_sec = 360

Restart the app or IDE extension after changing the file. In the CLI, run codex mcp list to confirm the entry and use /mcp inside a Codex session to inspect connected servers. See the official Codex MCP guide for the shared host configuration and all supported options.

Claude Code

claude mcp add --transport stdio webbrain -- npx -y @webbrain/mcp-server

The explicit transport matches the current Claude Code MCP configuration. Run claude mcp list after adding it to inspect server health.

Cursor

Add a local stdio server in Cursor’s MCP settings, or place this in the MCP JSON file Cursor uses. The shape follows Cursor’s local MCP server format:

{
  "mcpServers": {
    "webbrain": {
      "command": "npx",
      "args": ["-y", "@webbrain/mcp-server"]
    }
  }
}

OpenCode

Add this entry to ~/.config/opencode/opencode.json, using OpenCode’s local MCP server format:

{
  "mcp": {
    "webbrain": {
      "type": "local",
      "command": ["npx", "-y", "@webbrain/mcp-server"]
    }
  }
}

Run it manually

Manual launch is useful for diagnosing the listener, but not required during normal MCP use:

npx -y @webbrain/mcp-server

Leave that terminal open. Closing it closes the bridge listener. From a source checkout, run npm install, npm run build, then npm start inside mcp-server/.

Point WebBrain at the local listener

1. Start or restart your MCP client. Its WebBrain server must be running before the extension can connect.
2. Open WebBrain Settings. Go to General → Advanced → Cloud bridge.
3. Set the exact URL. Enter ws://127.0.0.1:17374/extension.
4. Enable Cloud bridge. The status should move from connecting to connected. The name is historical: this destination is local.
5. Verify end to end. Ask the MCP client to call webbrain_connection. “Connected” proves the client, local server, WebSocket listener, and extension handshake are all present.

Describe the browser job in natural language

In Codex, Claude Code, Cursor, 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.

Read something without changing the page

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.

Return predictable JSON

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.

Interact with the page

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.

The coding agent chooses webbrain_run for general reading or interaction and webbrain_extract 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.

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"
)

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.

What your MCP client uses for you

You normally choose an outcome, not a tool. Codex or Claude Code 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.

Ask for structured JSON

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.” Codex or Claude Code can translate those fields into the required schema and call webbrain_extract for you.

The function-shaped example below shows the equivalent tool call for client builders and debugging. Describe the selection logic in task; describe only the output shape in output_schema.

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"]
  }
)

• Use an object root with explicit properties and required fields.
• Ask for the narrowest data you need. A schema does not grant access to data that is not visible to the browser session.
• The tool is read-only, but the page text and result still travel to whichever LLM provider WebBrain is configured to use.
• 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.

Understand the run lifecycle

Codex and Claude Code normally 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.

A foreground call waits by default. For long work, the client can set wait: false and poll with webbrain_status.

# 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_…")

A WebBrain run timeout returns control to the MCP client but deliberately does not abort the browser task. Poll the returned run_id. This prevents a timeout from silently killing a task after it may already have taken a consequential action.

When WebBrain asks a question

A paused snapshot includes both a human-readable question and a clarify_id. Show the question to the user. Send their answer verbatim; do not infer it.

webbrain_respond(
  run_id: "mcp_…",
  clarify_id: "clarify_…",
  answer: "Use the Acme EU account."
)

Choose the smallest authority

MCP-client approval and WebBrain approval are separate layers. Your client may ask before it invokes webbrain_run; WebBrain may then ask before a consequential action on a particular origin. One approval does not replace the other.

Security boundaries you should keep

• Keep the listener local. It binds to 127.0.0.1. Do not forward port 17374, publish it through a container bridge, or proxy it onto a network.
• Loopback is not authentication. 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.
• Use Ask first. Read-only work is easier to verify and has a smaller blast radius.
• Keep the browser visible for Act. You can stop the run in the side panel, and unexpected navigation or typing should be treated as a reason to stop.
• Remember the provider boundary. 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.
• Do not mistake a timeout for a rollback. Aborting stops future steps; it cannot undo a sent email, submitted form, purchase, or other completed action.

For the complete design, see the security model, privacy and data flow, and modes, safety, and privacy guide.

Troubleshooting by symptom

Check the listener directly:

lsof -nP -iTCP:17374 -sTCP:LISTEN

No output means nothing is listening. If a PID appears and you did not expect it, identify the process before stopping it.

Environment configuration

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.

What this server deliberately does not do

• It does not launch a headless browser or create a fresh browser profile.
• It does not work through the Firefox build.
• It does not export cookies, credentials, or session storage.
• It does not expose WebBrain’s roughly fifty click, type, frame, screenshot, network, and DOM primitives directly to the MCP client.
• It does not make the bridge safe to expose remotely.
• It does not remove the need for a configured model inside WebBrain.

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.