Mbbrowser ControlV2 Integration

The reason MBAgent can "really operate Mbbrowser" lies in a communication protocol named Mbbrowser Client ControlV2. This article details how MBAgent establishes connection with Mbbrowser and common troubleshooting.

NOTE

Screenshot description: The "dual control" screenshot when MBAgent and Mbbrowser run simultaneously (Mbbrowser main window + MBAgent main window side-by-side) will be progressively supplemented in v1.x. This section uses text first to describe the collaboration between the two.

---

1. What Is Mbbrowser ControlV2?

Mbbrowser ControlV2 is a bidirectional communication protocol provided by Mbbrowser to external programs (including MBAgent) that allows:

• 🔍 Discover locally running Mbbrowser instances
• 🤝 Handshake with Mbbrowser instances
• 🔑 Login via Mbbrowser account
• 📦 Load Mbbrowser config (environments, proxy, fingerprint)
• 🚀 Start / stop Mbbrowser environments
• 🌐 Operate pages inside Mbbrowser environments

NOTE

Analogy: You can understand ControlV2 as Mbbrowser's "remote-control protocol". MBAgent is the remote control; Mbbrowser is the TV.

---

2. Three Connection Modes Between MBAgent and Mbbrowser

1. MBAgent Control (Recommended)

MBAgent auto-launches a Mbbrowser control service locally at startup; Mbbrowser connects as a client.

Use scenarios:

• Single Mbbrowser instance
• Most individual users
• Mbbrowser + MBAgent running on the same machine

2. ApiServer Control

Connect via Mbbrowser's built-in ApiServer interface (http://127.0.0.1:8186).

Use scenarios:

• Remotely control Mbbrowser
• Mbbrowser on another machine
• Automation scripts (Selenium / Puppeteer / Playwright)

3. Same Instance

MBAgent and Mbbrowser are in the same client instance, communicating internally directly.

Use scenarios:

• Development debugging
• Performance-sensitive scenarios

---

3. First-time Connection with Mbbrowser

Prerequisites

✅ Mbbrowser is started and logged in to an account ✅ MBAgent is installed ✅ The working directory selected at MBAgent startup has permissions

Auto Connection Flow

MBAgent automatically performs the following flow on startup:

[1] Start local ControlV2 service
    ↓
[2] Scan local Mbbrowser instances
    - Via UDP broadcast / local port scan
    - Find Mbbrowser's ControlV2 port
    ↓
[3] Handshake
    - Exchange protocol version numbers
    - Negotiate encryption method
    ↓
[4] Account login
    - MBAgent logs into ControlV2 with the Mbbrowser account
    - Auto-read Token
    ↓
[5] Config loading
    - Load all environments under the Mbbrowser account
    - Load proxy configuration under the Mbbrowser account
    ↓
[6] Capability detection
    - Test environment start / stop
    - Test page takeover
    - Test file operations
    ↓
[7] Connection success ✅

View Connection Status

1. Go to "Settings → Official Service Detection"
2. Click "Mbbrowser Client ControlV2" option
3. Click "Start Detection"
4. Displayed after a few seconds:
   • ✅ Normal: All checks passed
   • ⚠️ Abnormal: Specific step that failed
   • ⚪ Not enabled: ControlV2 not enabled
   • ⏳ Detecting: Currently detecting

---

4. Detection Result Interpretation

✅ Normal

Displays:

Mbbrowser Client ControlV2 is available
Real-time readiness round-trip detection has verified connection, login, configuration, and executable capability.

This means MBAgent can normally operate Mbbrowser.

⚠️ Abnormal: Connection Failed

Possible causes:

• Mbbrowser not started
• ControlV2 port occupied
• Firewall blocking

Troubleshoot:

1. Confirm Mbbrowser is started
2. Check Mbbrowser → Settings → whether ControlV2 is enabled
3. Close firewall / antivirus software and retry

⚠️ Abnormal: Account Not Logged In

Possible causes:

• Mbbrowser account Token expired
• MBAgent didn't read the Token

Troubleshoot:

1. Re-login the account inside Mbbrowser
2. Restart MBAgent

⚠️ Abnormal: Config Loading Failed

Possible causes:

• No environments created under the Mbbrowser account
• Mbbrowser database connection failed

Troubleshoot:

1. Create an environment inside Mbbrowser
2. Restart MBAgent

⚠️ Abnormal: Executable Capability Not Passed

Possible causes:

• Mbbrowser version incompatible with MBAgent
• Insufficient system permissions

Troubleshoot:

1. Confirm Mbbrowser is the latest version
2. Launch MBAgent with administrator privileges
3. Contact Mbbrowser customer support

---

5. Switch Mbbrowser Control Instances

If you have multiple Mbbrowser instances locally (development scenarios), you can switch:

Step 1: View All Mbbrowser Instances

1. Go to "Settings → Mbbrowser Client ControlV2"
2. Click the "Mbbrowser Instance" option
3. Displays the list of currently discovered Mbbrowser instances:

Mbbrowser instance #1 (default)
  - Port: 8186
  - Version: v3.0.0
  - Status: Connected

Mbbrowser instance #2 (dev)
  - Port: 8286
  - Version: v3.0.0
  - Status: Not connected

Step 2: Switch

1. Select target Mbbrowser instance
2. Click the "Switch" button
3. MBAgent disconnects the current instance and connects the new one
4. Note: Switching stops all current Mbbrowser operations

TIP

Daily use: 99% of users only need one Mbbrowser instance; no need to switch.

---

6. How AI Operates Mbbrowser

When MBAgent receives an "operate Mbbrowser" instruction, it automatically performs the following flow:

[1] AI parses the task
    "Open Mbbrowser 223223 store, check today's orders"
    ↓
[2] Call ControlV2 interface
    - control.browser.start({ environment_id: "223223" })
    ↓
[3] Mbbrowser starts the environment
    - Create / reuse 223223 environment
    - Apply fingerprint / proxy / cookie
    - Return browser_handle
    ↓
[4] MBAgent takes over the page via CDP
    - attach({ handle })
    - Receive page screenshot, DOM structure
    ↓
[5] AI analyzes the page + decides next step
    "Saw the order page, next extract numbers"
    ↓
[6] Execute actions
    - click / type / extract
    ↓
[7] Complete task, close environment (or keep open)
    ↓
[8] Summarize result for user
    "Today 23 orders, amount $1234.56"

Key Concepts

• handle: The "environment handle" returned by Mbbrowser to MBAgent, used to reference a specific environment
• attach: MBAgent takes over a Mbbrowser environment's page
• CDP: Chrome DevTools Protocol, the protocol used by Mbbrowser underneath

---

7. FAQ

Q1: MBAgent shows "Waiting for Mbbrowser CDP" after launch

Cause: Mbbrowser is not started, or the environment is not started.

Solution:

1. Confirm Mbbrowser is started and logged in
2. Manually start an environment inside Mbbrowser
3. MBAgent will auto-take-over

Q2: AI operations on Mbbrowser environment always fail

Possible causes:

• ControlV2 abnormal (see official service detection)
• Mbbrowser account quota exhausted
• Mbbrowser environment corrupted

Troubleshoot:

1. In Settings → Official Service Detection check whether ControlV2 is normal
2. Check the Mbbrowser account AI quota
3. Manually test the environment inside Mbbrowser

Q3: Screen is black after taking over Mbbrowser page

Possible causes:

• Mbbrowser just started, environment not yet ready
• Mbbrowser account requires secondary verification

Solution:

1. Wait 5-10 seconds and retry
2. Manually complete verification inside Mbbrowser

Q4: Can MBAgent control a remote Mbbrowser?

❌ No. MBAgent's Mbbrowser client ControlV2 connection is hard-limited to 127.0.0.1 at the implementation layer (ControlClientError::NonLoopbackEndpoint); any non-loopback IP address is rejected. Even if Mbbrowser's ControlV2 port is exposed to the outside (e.g. 0.0.0.0:8186), MBAgent will directly refuse the connection at the handshake stage.

Correct way to remotely control Mbbrowser:

• Use Selenium / Puppeteer / Playwright scripts to remotely call Mbbrowser's built-in ApiServer (http://127.0.0.1:8186) — see Section 2 above "MBAgent and Mbbrowser's Three Connection Modes → 2. ApiServer Control"
• In this scenario, MBAgent is not involved; just a regular HTTP client calling Mbbrowser ApiServer interfaces

NOTE

Why limited to loopback:

• ControlV2 protocol itself does not have strong identity verification; exposing TCP port on public network equals "giving Mbbrowser account control to anyone"
• MBAgent and Mbbrowser are assumed to run on the same machine, same account context; loopback is the lowest-risk boundary

Q5: Can MBAgent be used without operating Mbbrowser?

✅ Absolutely. MBAgent's core functions (chat, documents, code, knowledge base) do not depend on Mbbrowser. Only when you explicitly request operating Mbbrowser account environments will the ControlV2 connection be established.

---

8. Best Practices

Launch Order

Recommended launch order:

1. Mbbrowser (start first and log in)
2. MBAgent (start later, auto-connects)

Do not reverse.

When Not Used for a Long Time

If you won't use Mbbrowser operations for a long time:

1. Close the "Mbbrowser RAG Knowledge Base" and "Mbbrowser Client ControlV2" sidebar entries inside MBAgent
2. Reduce Mbbrowser operations in tasks
3. Save Mbbrowser account resource usage

Multi-person Collaboration

If multiple team members share one Mbbrowser account:

1. Each person's MBAgent can connect independently
2. But simultaneously operating one environment will conflict
3. Recommend staggered use, or open independent Mbbrowser sub-accounts for each person

---

Next: Permission Management & Safe Usage → Let AI work with peace of mind.