MCP for AI agents to manage NextCore Browser

Connect Claude Code, Claude Desktop, Cursor, VS Code, Gemini CLI, Codex and 15 other assistants to NextCore Browser to create, open, arrange and back up profiles, and to work with pages inside each profile in plain language.

MCP (Model Context Protocol) is a common standard that lets AI assistants use external tools. NextCore Browser includes an MCP server that runs on its own Local API: your AI assistant connects to it and works with profiles just as you would by clicking in the app.

For example, you can tell your assistant:

• "List the profiles in the Farm máy 1 group that have proxy errors."
• "Create 10 profiles named Shop 01–10 and assign the proxies in this list to them in order."
• "Open 4 profiles from the Farm máy 2 group and arrange them in a 2×2 grid on the secondary screen."
• "Back up the Shop Ngọc Lan profile to drive D."
• "Open the Shop 03 profile, go to the Facebook group page and tell me how many posts are waiting for approval."

The assistant works with pages inside each profile, keeping that profile's sign-ins, proxy and extensions, using a toolset with the same names as the official Playwright MCP (browser_*).

#Turning it on and connecting

SETTINGS › AI agent (MCP), turn on Enable AI agent (MCP) (on by default). The server only listens on this machine: http://127.0.0.1:<port>/mcp, and requires a token.

Below the switch is the Assistants on this computer block. The app knows how to connect 21 assistants (since 0.3.167):

Assistants the app finds on the machine appear as cards at the top of the block. The rest are grouped in the Other assistants (N) line; click Show all to expand it, and click Write config anyway if you installed an assistant in a custom folder the app cannot see.

#One-click connection

Click Connect on an assistant's card. The card changes to Setting up and runs each step, ticking each one as it completes:

1. Write MCP config into the right file for that assistant (for Windows, macOS or Linux) with its own token. If the file already has other configuration, the app only adds the nextcore-browser entry, keeping comments and other servers intact; the old version is left next to the file with a .ncb-bak suffix. If the file has a syntax error, the app stops and does not overwrite it.
2. Self-check: the app reads back the entry it just wrote and requests the tool list exactly as the assistant will. When done, the card shows Ready · N tools.
3. Install the NextCore Browser usage guide for the assistant (the nextcore-browser skill for Claude Code, an instructions file for other assistants).
4. Claude Code only: the app asks whether to Allow NextCore Browser tools without asking each time. This permission is removed when you disconnect.
5. It records the default profile the assistant will use, and what to do so the assistant loads NextCore Browser: start a new session (command-line assistants) or quit fully and reopen (code editors).

Click Try now to open the assistant with the first sample prompt. Command-line assistants open in a terminal or in Orca's «NCB · Thử ngay» tab; other assistants open with the sample prompt prefilled, or the app copies the prompt for you to paste. The Next steps card has 4 more sample prompts (list profiles, capture a page, find groups for GROUP CRAWL, view the machines in your team) with a Copy button.

Every time you open SETTINGS, the app rechecks the connected assistants; the card shows the check time and the last use.

• Claude Desktop connects through the mcp-remote bridge (requires Node.js). The app pins a tested version of mcp-remote; on Windows the command runs through cmd /c.
• Windsurf and Devin Desktop only accept up to 100 tools across all servers, so the app writes the co-ban toolset (see the Toolsets table below).
• If Continue has no config.yaml, the app creates a new file with all the keys Continue requires.

#When the card says Not connected

The card shows the reason and how to fix it right below. Most of the time you only need to click Fix it for me: the app rewrites the configuration and checks again.

The ⋯ menu on the card has Check again, Run full setup again, Open file folder and Disconnect. Disconnecting revokes the token immediately and removes the nextcore-browser entry along with the guide and permissions the app added; if nothing else in the file changed since connecting, the app restores the exact .ncb-bak version.

The Recent calls block lists each time an assistant called a tool.

The Try NextCore Browser & Super Agent row (requires Claude Code to be connected): click Start, and the app opens a new Claude tab in Orca in the open repo and types an opening prompt so the agent introduces what it can do with the app. The ⋯ menu lets you copy that prompt to paste into another agent.

#Connecting by hand

For other assistants, or if you want to edit the file yourself: open Advanced at the bottom of the block. It has the Local API port and token, Command line to paste into a terminal (Claude Code) (Copy command button) and Manual config for other clients (JSON) (Copy JSON button). The command and JSON are copied with the real token; the screen only shows ••••.

{
  "mcpServers": {
    "nextcore-browser": {
      "url": "http://127.0.0.1:19880/mcp",
      "headers": { "Authorization": "Bearer <token>" }
    }
  }
}

#Toolsets

The full set has nearly 190 tools, which is heavy for assistants with a tool limit. Add ?bo= to the address to choose a smaller set:

Smaller sets only shorten the list the assistant sees; an assistant that calls a tool outside the set by name still works.

#English tool names

Since 0.3.167, /mcp returns the English contract: tool names, parameter keys at every level, enumerated values, descriptions, results, instructions and prompts are all in English. For example ncb_xem_profile becomes ncb_profile_get, and ncb_gc_goi_y { tuKhoa } becomes ncb_gc_suggest { keyword }. The Vietnamese names on this page can still be called.

• Older assistants or scripts that call with Vietnamese names, keys or values keep working as before, including when the command is forwarded to a workstation still on an older version.
• Internal scripts that need to read results with Vietnamese keys can add ?contract=1 to get the old contract.
• ?lang=vi or ?lang=en (can be combined with ?bo=, for example /mcp?bo=app&lang=vi) chooses the language of error messages.

Since 0.3.168:

• Error messages and hints in results name the English tools (ncb_page_read, ncb_profile_select…) and no longer tell the assistant to call Vietnamese names.
• ncb_app_call and ncb_settings accept English keys at the top level ({ name, params }, { changes }). Before this, calling with English keys made ncb_app_call report a missing command and ncb_settings change nothing.
• nck_apply decisions return actions in the form { tool, params }, with params using English keys, so they can be called again right away.
• When a command from the main machine is forwarded through the station to a sub-machine running 0.3.168, the sub-machine returns English names and keys directly. Sub-machines on older versions still work, and the main machine translates automatically.

Errors have stable NCB-xxxx codes: 1xxx protocol (for example NCB-1003, no such tool), 2xxx session and permissions, 3xxx workstations, 9000 an internal tool error. The error text follows the chosen language; the code is in error.data.code of the JSON-RPC response and _meta["vn.nextcore/error"] of the tool result. Compare codes, not text.

#Results state what NextCore Browser did

Since 0.3.167, results of test and coordination commands (nck_run, ncb_e2e, ncb_e2e_lo, nck_apply when it returns a decision, ncb_terminal after assigning work) include a summary of what NextCore Browser just did, taken from that run's own measurements, in _meta["org.homestaynextcore/attribution"]. Failed runs, or runs that measured nothing, do not include it. The assistant is instructed to copy the summary once at the end of its report to you, so you know which errors the app's checks found.

#Self-diagnosing the connection (ncb_doctor)

Since 0.3.168, the assistant calls ncb_doctor when the connection has a problem. The tool checks 9 items and marks each as passing, needing attention or broken, with how to fix it:

The result contains no access keys or data folder paths, so it is safe to paste into an issue when reporting a bug.

The app also publishes an MCP server card at http://127.0.0.1:19880/mcp/server-card and /.well-known/mcp: name, version, supported protocol versions and authentication method. Reading the card needs no key; when MCP is off this address returns 404.

#Tools

Destructive tools are off by default, so assistants cannot see them. Turn on the Allow destructive tools switch in SETTINGS › AI agent (MCP).

The tools ncb_trang_mo_url, ncb_trang_doc, ncb_trang_bam, ncb_trang_go and ncb_trang_chup are legacy: they still work for existing scripts but are not shown in the app and co-ban sets. For new work, use ncb_chon_profile + browser_*.

#NextCore Command: coordinating agents across machines (ncb_terminal)

One tool; the hanhDong parameter chooses the action. may is nay (this machine) or a machine id taken from may.

Tasks in the task book go through six stages (dang → bao-xong → da-kiem → nghiem-thu → cho-phat-hanh → toi-tay). hanhDong: "viec" with lam: "ds" returns stage + stageLabel for each task; lam: "buoc" with id and stage moves a task to the next stage. Skipping or going back a stage is refused and nothing is written.

Since 0.3.174, when you call a tool on another machine over the LAN and the LAN drops: read-only tools and commands that had not started yet are retried automatically through the station; tools that write still return a «có thể đã chạy» (may have already run) error. ncd_link_xem returns links of the form homestaynextcore.org/nextcore-design/<mã>.

Since 0.3.169, ncb_db_sua accepts dangTuong, dangGroup, quyenTuong, dangDuoiTen (post to a personal timeline or Page, who can see it, which name to post as); ncb_luong_nut returns sample parameters for the read file, download file, loop and type nodes.

Example of assigning a macOS build to the Mac:

{ "hanhDong": "giao", "hdh": "darwin", "chu": "Phát hành bản 0.3.92 cho macOS theo docs/phat-hanh-da-nen-tang.md" }

The message sent to the agent on the other side states its source: «[Việc giao từ <máy> qua NEXTCORE TERMINAL — trả lời «Đã nhận» rồi làm]» (Work assigned from via NEXTCORE TERMINAL; reply «Đã nhận» (Received), then do it). A few minutes later, call doc or giam-sat to check. Sending raw keystrokes to the terminal (term*) is not available to MCP.

#NextCore Kernel (nck_apply)

Since 0.3.158, NextCore Command decisions (picking work, scoring, unblocking, acceptance, slicing large tasks) go through nck_apply. The agent describes the situation and Kernel returns a decision; the agent does not receive, and does not need to know, the rules inside.

{ "module": "nck.command", "tinhHuong": { "loai": "cham-diem", "…": "dữ kiện của tình huống" } }

Kernel runs on the NextCore server. NCB sends the question with the account's license and a signature from the machine's device key, so only machines that are signed in can call it.

The nck.command module also returns a code cell map of the open repo: { "loai": "ban-do-o" } ⇒ clusters of tightly linked files (by imports and git co-change history), with line counts, change frequency and whether they have tests; { "loai": "o-cua-tep", "tep": "<đường dẫn>" } ⇒ which cell that file belongs to. Use it to slice large tasks along the right boundaries. The first build takes a few seconds; later calls only reread changed files.

During short outages NCB decides locally (nguon: "cuc-bo"), for up to 24 hours since the server last answered. When the server blocks for rapid calls, NCB does not switch to deciding locally.

#Working with pages in a profile

The usual order an assistant follows:

1. ncb_liet_ke_profile to get the id (if the user gives a name, filter with q).
2. ncb_chon_profile { "id": "…" }: binds this session to the profile and opens it if it is not open. From then on, every browser_* runs on that profile.
3. browser_navigate to the page to work on, then browser_snapshot to read the accessibility tree. Each element has a ref.
4. browser_type / browser_click with that ref; browser_take_screenshot or browser_snapshot to check the result.
5. When done: ncb_tha_profile releases the profile for other sessions (the browser stays open).

• One MCP session holds one profile. To run several profiles in parallel, open several sessions (several agents). If another session holds the profile, ncb_chon_profile returns an error; ncb_phien tells you who holds it.
• Clicks and typing are real mouse and keyboard events, not JavaScript commands inside the page.
• Each open profile still returns its own wsEndpoint if you want to connect Playwright or Puppeteer from a script.

#Typing passwords the agent cannot see

Since 0.3.149, when a session holds a profile, the profile's secret note fields (PWD ACCOUNT, 2FA key, PWD EMAIL, COOKIE) are loaded as named secrets. In every browser_* result (page tree, console, files written), the real value is replaced with <secret>PWD_ACCOUNT</secret>. The agent types by name: browser_type with the text PWD_ACCOUNT puts the real password into the field, while the agent only sees the name.

#NextCore E2E: page testing

The ncb_e2e* set (NextCore E2E) tests your website on real profiles (already signed in), with no need to set up test accounts:

ncb_e2e and ncb_e2e_lo accept quyTac to set project-specific thresholds (touch target size, AA or AAA contrast level, LCP/CLS thresholds, regions to ignore).

#Safety

• Only this machine can call it (127.0.0.1), a token is required, and requests from web pages are rejected, as with the Local API. Each assistant connected with Connect has its own token that can be revoked separately.
• No tool returns proxy passwords. When Mask login details is on (SETTINGS), ncb_liet_ke_profile / ncb_xem_profile mask PWD ACCOUNT, 2FA CODE, PWD EMAIL and COOKIE. An agent can only read the raw value of a field through ncb_o_bi_mat, one field at a time, and every call is logged in Recent calls.
• Commands that touch the data folder (choose, move, reuse an old folder), quit or restart the app only run on that machine itself; calls from a main machine controlling it through the station (ncb_chon_thiet_bi) are refused.
• Anyone who has the token and can run programs on your machine can control your profiles. Keep the token like a password; if it leaks, change it under Advanced or Revoke that assistant.