MCP Server

MCP (Model Context Protocol) là cách chuẩn để các công cụ LLM như Claude Code, Cursor, Claude Desktop kết nối tới công cụ bên ngoài — Veilus nói giao thức này qua stdio, nên một LLM có thể thay bạn nhập proxy, tạo và mở profile, điều khiển trang của profile đang chạy, viết và chạy script Veilus Flow, và đặt lịch cho chúng.

Giống REST API, tính năng này cần bật API cục bộ trước, từ trang API & MCP trong sidebar của app — trang đó cũng đúc token bạn cần dưới đây.

Kết nối

Binary Veilus có lệnh con mcp nói MCP qua stdio. Client cần đường dẫn tới binary đó và token của bạn, truyền qua biến môi trường VEILUS_API_TOKEN.

Claude Code

claude mcp add --scope user veilus -e VEILUS_API_TOKEN=<token> -- "<path to Veilus>" mcp

--scope user cho Claude Code thấy Veilus ở mọi thư mục; không có nó thì chỉ thấy ở đúng thư mục bạn đứng lúc chạy lệnh.

Cursor / Claude Desktop

Thêm đoạn này vào cấu hình MCP server của client:

{
  "mcpServers": {
    "veilus": {
      "command": "<path to Veilus>",
      "args": ["mcp"],
      "env": {
        "VEILUS_API_TOKEN": "<token>"
      }
    }
  }
}

Trang API & MCP tự điền đường dẫn binary thật và token cho bạn ngay khi bạn đúc token — copy đoạn cấu hình từ đó thay vì tự gõ.

Danh sách tool

Profile

list_profiles

List Veilus browser profiles, with their running state. A running profile also carries `cdpUrl` (see launch_profile).

create_profiles

Create 1 to 50 new browser profiles in one call. With proxy_pool_id (a static pool, e.g. from import_proxies), each new profile gets the pool's least-loaded slot (free slots first, lowest index on ties) and its timezone and language are generated to match that slot's exit-IP geo; a profile whose slot has no known geo is listed in `failed` and NOT created. Without proxy_pool_id the fingerprint is random. The whole call is rejected, creating nothing, if it would exceed the plan's profile limit. `name_template` replaces {n} with 1, 2, ...; `tags` are tag names. `failed[].index` is that same n. With identity_dataset_id (a fixed dataset) each new profile takes one unassigned row, and the call is refused if count exceeds the unassigned rows; content_dataset_id (a consume dataset) goes to every new profile's Content slot.

Tham số	Kiểu	Bắt buộc	Mô tả
content_dataset_id	string	không	UUID of a consume dataset
count	integer	có
identity_dataset_id	string	không	UUID of a fixed dataset (create_dataset)
name_template	string	không	Profile name; {n} becomes 1, 2, ...
os	string	không
proxy_pool_id	string	không	UUID of a static proxy pool
tags	string[]	không	Tag names

launch_profile

Launch a profile: waits for its browser to finish starting, then returns `{pid, cdpUrl}`. `cdpUrl` (http://127.0.0.1:<port>) is the profile's own Chromium DevTools endpoint: any CDP client — Playwright `connectOverCDP`, Puppeteer `connect`, browser-use, playwright-mcp — can drive the profile through it with its fingerprint and proxy. It has no authentication: any local process can use it while the profile runs. If the profile pool is already full this fails immediately with a 409 (`REST returned 409 ...`) rather than queuing.

Tham số	Kiểu	Bắt buộc	Mô tả
profile_id	string	có	Profile UUID

stop_profile

Stop a profile's browser and release everything its launch held. Stopping a profile that is not running also succeeds. Returns an empty result.

Tham số	Kiểu	Bắt buộc	Mô tả
profile_id	string	có	Profile UUID

set_profile_variables

Replace ALL stored variables of one profile with `variables` - not a merge: names you omit are deleted, {} clears them. Names are UPPER_SNAKE_CASE, at most 64 variables, values up to 32 KiB. They are delivered only to runs of APPROVED scripts (run_batch, schedules, and run_script once the user has approved the script) as process.env.VEILUS_VAR_<NAME>; a run_script trial of an unapproved script gets only the variables passed to that call. A variable passed to the run itself wins on the same name. Returns the stored names, never the values.

Tham số	Kiểu	Bắt buộc	Mô tả
profile_id	string	có	Profile UUID
variables	object	có	The complete new set of variables

Proxy

import_proxies

Create a static proxy pool from proxy lines (host:port, host:port:user:pass or user:pass@host:port). Prefix a line with socks5:// for a SOCKS5 proxy; http:// or no prefix means HTTP; https:// is rejected (TLS to the proxy is not supported). Bad lines are reported in `rejected` by line number (counting from 1) and do not block good ones; if no line is valid, nothing is created. Returns pool_id for create_profiles or assign_proxy_pool. Passwords are stored but never returned.

Tham số	Kiểu	Bắt buộc	Mô tả
lines	string[]	có	One proxy per element
name	string	có
type	string	không

list_proxy_pools

List proxy pools: `pool_id`, `name`, `kind` (static or rotating), `entry_count` and `countries` detected for their exit IPs. Never returns credentials.

test_proxy

Test every proxy in a pool now: alive or dead, latency, exit IP and its country and timezone. Refreshes the pool's cached geo, which create_profiles uses. A dead proxy can take up to about 10 seconds.

Tham số	Kiểu	Bắt buộc	Mô tả
pool_id	string	có	Proxy pool UUID

assign_proxy_pool

Assign a proxy pool to existing profiles, one slot each. Refuses the whole call (nothing assigned) if any profile already has a proxy or pool, listing them; pass force: true to replace. Does NOT change the profiles' timezone: if the new proxy is in another country, launch_profile will be blocked by the geo check. New profiles should get their pool through create_profiles instead.

Tham số	Kiểu	Bắt buộc	Mô tả
force	boolean	không	Replace an existing proxy. Default false
pool_id	string	có	Proxy pool UUID
profile_ids	string[]	có

get_profile_proxy

Show which proxy a profile goes out through: its pool and slot, the slot's host:port, whether it needs auth, and the slot's detected country and timezone. Never returns the password.

Tham số	Kiểu	Bắt buộc	Mô tả
profile_id	string	có	Profile UUID

Điều khiển trang

navigate

Load a URL in the tab of a RUNNING profile and wait for its load event (up to 15 s); on timeout it PROCEEDS ANYWAY and the result says the page is still loading - then call wait_for_element for what you need before reading the page. The profile must already be open - call launch_profile first; this never opens it.

Tham số	Kiểu	Bắt buộc	Mô tả
profile_id	string	có	UUID of a running profile (launch_profile first)
url	string	có

snapshot

Accessibility snapshot of the current page of a running profile: one line per element with role, name and [id=N]; pass N as node_id to click or type. Ids change when the page changes - take a new snapshot after navigating or clicking. Lists at most 150 elements and 64 KiB; truncated: true means the page has more - use wait_for_element with a CSS selector to reach an element that is not listed. Elements inside same-origin iframes follow a `--- iframe URL ---` line and work with click and type like any other; a cross-origin iframe gets a `(cross-origin …)` line with its URL but its elements are not listed - navigate to that URL to work inside it.

Tham số	Kiểu	Bắt buộc	Mô tả
profile_id	string	có	UUID of a running profile (launch_profile first)

click

Click an element of a running profile's page by node_id with a real mouse: the pointer moves to a point inside the element, then presses and releases. Fails if the page changed since the snapshot (take a new one), if the element has no visible box (hidden or zero-size — click its visible label or parent), or if another element covers it (the error names it — close or scroll past it first). A JavaScript alert/confirm/prompt that the action opens is answered at once: `dialog` "dismiss" (default, i.e. Cancel) or "accept" (OK), with `prompt_text` as the typed answer to a prompt; the result says which dialog opened and how it was answered.

Tham số	Kiểu	Bắt buộc	Mô tả
dialog	string	không
node_id	integer	có	node_id from snapshot ([id=N]) or wait_for_element
profile_id	string	có	UUID of a running profile (launch_profile first)
prompt_text	string	không

type

Focus an element by node_id and type text into it, one key event per character (at most 5000 characters). Replaces the field's current content: existing text is removed before typing. If the result notes that the value could not be confirmed (masked, length-limited or auto-formatted fields), verify the field with snapshot or evaluate_js.

Tham số	Kiểu	Bắt buộc	Mô tả
node_id	integer	có	node_id from snapshot ([id=N]) or wait_for_element
profile_id	string	có	UUID of a running profile (launch_profile first)
text	string	có

press_key

Press one named key in a running profile's page: Enter, Tab, Escape, ArrowUp, ArrowDown, ArrowLeft, ArrowRight, Backspace, Delete or Space. If no input is focused, the LAST input on the page is focused first. For text use `type`. A JavaScript alert/confirm/prompt that the action opens is answered at once: `dialog` "dismiss" (default, i.e. Cancel) or "accept" (OK), with `prompt_text` as the typed answer to a prompt; the result says which dialog opened and how it was answered.

Tham số	Kiểu	Bắt buộc	Mô tả
dialog	string	không
key	string	có
profile_id	string	có	UUID of a running profile (launch_profile first)
prompt_text	string	không

scroll

Scroll a running profile's page by `amount` pixels (1 to 20000) in direction up, down, left or right.

Tham số	Kiểu	Bắt buộc	Mô tả
amount	integer	có
direction	string	có
profile_id	string	có	UUID of a running profile (launch_profile first)

wait_for_element

Wait until a CSS selector matches an element in a running profile's page (polls every 200 ms; timeout_ms 1 to 30000, default 5000) and return its node_id for click or type. Use after navigate or click to wait for the next page.

Tham số	Kiểu	Bắt buộc	Mô tả
profile_id	string	có	UUID of a running profile (launch_profile first)
selector	string	có	CSS selector
timeout_ms	integer	không

evaluate_js

Run a JavaScript expression in a running profile's page and return its value as `text`, JSON-encoded (strings come back quoted); promises are awaited. `undefined` comes back as the text `(undefined)`, not JSON `null`. A thrown error comes back as text starting with [JS Error] — this is a normal call result, not a tool failure. Results over 64 KiB are cut and flagged truncated: true. A synchronous loop is stopped by the PAGE ITSELF after about 9 s; its result also comes back as ordinary [JS Error] text. A promise that never settles instead makes the call itself fail after 10 s with a timeout error. This is NOT a sandbox: it runs with the full rights of the logged-in page (reads cookies, sends requests as the user). A JavaScript alert/confirm/prompt that the action opens is answered at once: `dialog` "dismiss" (default, i.e. Cancel) or "accept" (OK), with `prompt_text` as the typed answer to a prompt; the result says which dialog opened and how it was answered.

Tham số	Kiểu	Bắt buộc	Mô tả
dialog	string	không
expression	string	có
profile_id	string	có	UUID of a running profile (launch_profile first)
prompt_text	string	không

set_file

Attach a file to a file input (<input type=file>, often shown as a "Choose File" button) of a running profile's page by node_id, instead of clicking it - a click opens the system file picker, which cannot be controlled. Only files inside the app's uploads folder (~/.veilus/data/uploads) are allowed: pass the file name, or an absolute path inside that folder; anything else is refused. Ask the user to copy the file there first.

Tham số	Kiểu	Bắt buộc	Mô tả
node_id	integer	có	node_id from snapshot ([id=N]) or wait_for_element
path	string	có	file name inside ~/.veilus/data/uploads
profile_id	string	có	UUID of a running profile (launch_profile first)

Script

list_scripts

List every script, newest first, without its source: `scriptId`, `name`, `description`, `version`, `mode` (`raw` or `dsl`), `origin` (`mcp` if an agent wrote it, `app` if the user did), `approved` and `updatedAt`. Check here before save_script so you update an existing script instead of saving a duplicate.

save_script

Save a Playwright (TypeScript) script into Veilus Flow. Without script_id: create a new script; with script_id: replace its source. Contract - violations are rejected with line numbers: (1) connect with chromium.connectOverCDP(`http://127.0.0.1:${process.env.VEILUS_DEBUG_PORT}`); (2) no chromium.launch/launchPersistentContext; (3) use browser.contexts()[0], not newContext(); (4) no setUserAgent/setViewportSize - identity belongs to the profile; (5) errors must exit non-zero: main().catch((e) => { console.error(e); process.exit(1); }); (6) import only playwright and Node built-ins; (7) end main() with `await browser.close()` - it only disconnects from the profile's browser and lets the script exit; without it the run hangs. Read variables via process.env.VEILUS_VAR_<NAME> (names are UPPER_SNAKE_CASE); print what you need to see with console.log to stdout. A newly saved script is not approved: run_script can run it (on at most 3 profiles), schedules wait until the user approves it in the app. `name` is used only when creating; updating (with script_id) does not rename, and only scripts saved by an agent can be updated. Returns `scriptId` (this script's id — pass as script_id to get_script or to save_script again), `version` and `approved`.

Tham số	Kiểu	Bắt buộc	Mô tả
description	string	không
name	string	có
script_id	string	không	UUID of the script whose source to replace; omit to create a new script
source	string	có	The full TypeScript source

get_script

Read the source and approval state of a Raw script, to fix it and save_script it again. Returns `scriptId`, `name`, `description`, `version`, `source`, `approved` and `origin`.

Tham số	Kiểu	Bắt buộc	Mô tả
script_id	string	có

run_script

Run a script on the given profiles. Returns the run IMMEDIATELY, without waiting for it to finish; its `id` is the run_id for get_run_result.

Tham số	Kiểu	Bắt buộc	Mô tả
profile_ids	string[]	có	UUIDs of the profiles to run on
script_id	string	có	Script UUID
variables	object	không	Variables for the script, read in the script as process.env.VEILUS_VAR_<NAME>

compile_script

Compile a drag-and-drop DSL script into runnable code. Does not run it. Agents writing scripts should use save_script instead.

Tham số	Kiểu	Bắt buộc	Mô tả
dsl	object	có	DSL script body
target	string	không	Compile target

Chạy hàng loạt

run_batch

Run an APPROVED script on many profiles for real. Returns the run IMMEDIATELY; its `id` is the run_id for get_run_result. Unlike run_script (a trial on at most 3 profiles, no approval needed), the script must have been approved by the user in Veilus → Flow, otherwise the call is refused. A profile id that does not exist is counted as a failed profile of the run, not rejected (unlike create_schedule, which refuses unknown ids with 404). concurrency (default 3, 1-16, capped by get_capacity's `max`) is how many profiles run at once; stagger_ms (default 1500, 0-600000 i.e. 10 minutes) is the pause between launches; use get_capacity to choose.

Tham số	Kiểu	Bắt buộc	Mô tả
concurrency	integer	không
profile_ids	string[]	có
script_id	string	có	UUID of an approved script
stagger_ms	integer	không
variables	object	không	Variables for this run, read as process.env.VEILUS_VAR_<NAME>

get_capacity

How many browsers are open (active), waiting for a slot (queued) and allowed at once (max) on this machine. Use it to choose run_batch concurrency.

Lịch chạy

create_schedule

Create a schedule that runs an APPROVED script on the given profiles at set times. The script must already be approved by the user in Veilus → Flow: an unapproved script is refused now, not skipped later. schedule_type: interval (interval_minutes, with interval_unit minutes or seconds, at least 5 seconds), daily (daily_hour and daily_minute, the computer's local time), weekly (daily_hour, daily_minute and weekly_day, 0 = Sunday), cron (cron_expr, 5 fields) or once (run_at, a future RFC 3339 time with offset; the schedule runs once and then turns itself off). concurrency (default 1, 1-16) and stagger_ms (default 0, 0-600000 i.e. 10 minutes) apply to every run. Returns the schedule, including nextRunAt.

Tham số	Kiểu	Bắt buộc	Mô tả
concurrency	integer	không
cron_expr	string	không
daily_hour	integer	không
daily_minute	integer	không
enabled	boolean	không
interval_minutes	integer	không
interval_unit	string	không
name	string	có
profile_ids	string[]	có
run_at	string	không	RFC 3339 with offset, e.g. 2026-10-04T09:00:00+07:00; required for once
schedule_type	string	có
script_id	string	có	UUID of an approved script
stagger_ms	integer	không
weekly_day	integer	không

list_schedules

List every schedule: its script, target profiles, timing, enabled flag, and next and last run times.

set_schedule_enabled

Turn a schedule on or off. Turning it on recomputes the next run from now and requires its script to still be approved; turning it off keeps the schedule and its run history.

Tham số	Kiểu	Bắt buộc	Mô tả
enabled	boolean	có
schedule_id	string	có	Schedule UUID

run_schedule_now

Run a schedule once right now, without waiting for its timer. Returns the run IMMEDIATELY; its `id` is the run_id for get_run_result. Refused while the schedule already has a run in progress, or if its script is not approved.

Tham số	Kiểu	Bắt buộc	Mô tả
schedule_id	string	có	Schedule UUID

Theo dõi

list_runs

List the most recent runs, newest first: status and profile counts, without per-profile detail (get_run_result has that). Without schedule_id it lists runs of every schedule and of run_script and run_batch. limit defaults to 20, at most 100.

Tham số	Kiểu	Bắt buộc	Mô tả
limit	integer	không
schedule_id	string	không	Only this schedule's runs

get_run_result

Result of a run by `run_id` — use after calling run_script.

Tham số	Kiểu	Bắt buộc	Mô tả
run_id	string	có	UUID returned by run_script

Bộ dữ liệu

create_dataset

Create a dataset: a table stored in Veilus that approved scripts read per profile. mode `fixed`: each profile gets ONE row for good (accounts); its columns arrive as process.env.VEILUS_VAR_<COLUMN>. mode `consume`: each run takes `rows_per_run` (1-50, default 1) unused rows; a failed run gives them back, a successful run marks them used; they arrive as VEILUS_VAR_ROWS (JSON array of {COLUMN: value}) and, when rows_per_run is 1, also one variable per column. VEILUS_VAR_ROW_INDEX is the row's number. Columns are UPPER_SNAKE_CASE; ROWS, ROW_INDEX, PROFILE_ID, RUN_ID and DEBUG_PORT are reserved. Mark a column `secret: true` for passwords: it is stored and given to approved scripts, but no tool ever returns it. Bad rows are reported in `rejected` by row number (from 1). Returns `datasetId`.

Tham số	Kiểu	Bắt buộc	Mô tả
columns	object[]	có
mode	string	có
name	string	có
rows	object[]	không	One object per row, keyed by column name; every value must be a string — convert numbers and dates to text before sending
rows_per_run	integer	không

append_dataset_rows

Add rows to a dataset, in the same shape as create_dataset's `rows`. Bad rows are reported in `rejected` by row number and do not block good ones.

Tham số	Kiểu	Bắt buộc	Mô tả
dataset_id	string	có	Dataset UUID
rows	object[]	có	One object per row, keyed by column name; every value must be a string — convert numbers and dates to text before sending

list_datasets

List datasets: id, name, mode, columns with their secret flag, rowsPerRun, row counts (total and assigned for fixed; available, reserved and used for consume) and how many profiles use each. Never returns row values.

get_dataset_rows

Read a dataset's rows in order: `limit` rows (default 100, at most 500) from `offset`. Each row has its index, its values, and for a fixed dataset the profile it is assigned to, for a consume dataset its state. Secret columns are always left out of `values`.

Tham số	Kiểu	Bắt buộc	Mô tả
dataset_id	string	có	Dataset UUID
limit	integer	không
offset	integer	không

assign_dataset

Assign a dataset to existing profiles. A fixed dataset goes to each profile's Identity slot and gives it one unassigned row (lowest index first); profiles left without a row are named in `withoutRow` and get nothing — never share one account between profiles. A consume dataset goes to the Content slot. Refuses the whole call if a profile already has a different dataset in that slot, unless force: true; refuses column names that also exist in the dataset in the profile's other slot. Every later run of an APPROVED script on those profiles carries the data; schedules and run_batch need no new field.

Tham số	Kiểu	Bắt buộc	Mô tả
dataset_id	string	có	Dataset UUID
force	boolean	không	Replace a dataset already in the slot. Default false
profile_ids	string[]	có

unassign_dataset

Remove a dataset from profiles. For a fixed dataset their rows become unassigned again. Profile ids that no longer exist are accepted, so rows held by deleted profiles can be freed.

Tham số	Kiểu	Bắt buộc	Mô tả
dataset_id	string	có	Dataset UUID
profile_ids	string[]	có

reset_dataset_rows

For a consume dataset: put every used row back to available, so runs take them again. Returns how many rows changed.

Tham số	Kiểu	Bắt buộc	Mô tả
dataset_id	string	có	Dataset UUID

Xem thêm

Để LLM làm tự động hoá giúp bạn đi qua trọn việc mà các tool này dùng cho, và các quy tắc an toàn chúng tuân theo.