Local API

The Local API lets your own tools list and start profiles, run workflows and read results. It is an HTTP server inside the app that listens on 127.0.0.1 only: nothing outside this computer can reach it.

Turn it on

1. Open Settings → API & MCP.
2. Turn on the Local API. The default port is 50325.
3. Create an API key: give it a name and pick its scopes. The key (mzb_…) is shown once; MZBase keeps only its hash.

Scopes

Scope	Allows
read	every GET route
write	create, edit and delete profiles; set account status
control	start and stop profiles; check and change proxy IPs
run	start and cancel workflow runs
cdp	get the browser’s DevTools endpoint when a profile starts; page tools over MCP

A key can also have a rate limit per minute and a maximum of concurrent runs. A call without the needed scope answers 403 API_SCOPE_DENIED.

Every authenticated call is written to the API audit log (route and query, never bodies or secrets), kept 90 days.

Calling it

Send the key as a bearer token:

curl -H "Authorization: Bearer $MZB_KEY" http://127.0.0.1:50325/profiles

GET /health needs no key and answers { "status": "ok" }.

Requests and responses are JSON with camelCase fields. Errors use one format:

{ "error": { "code": "PROFILE_NOT_FOUND", "message": "…", "details": {} } }

Routes

Method	Path	Does
GET	/health	Liveness, no key
GET	/profiles?search=&folderId=&tag=	List profiles
POST	/profiles	Create a profile
GET	/profiles/{id}	One profile
PATCH	/profiles/{id}	Update a profile
DELETE	/profiles/{id}	Move a closed profile to Trash
POST	/profiles/{id}/start	Open a profile; returns its DevTools endpoint with the cdp scope
POST	/profiles/{id}/stop	Close a profile
GET	/profiles/{id}/status	Running state
GET	/proxies	List proxies (never passwords)
POST	/proxies/{id}/check	Re-check a proxy
POST	/proxies/{id}/change-ip	Ask the provider for a new IP
GET	/accounts	List accounts (never passwords or 2FA seeds)
POST	/accounts/status	Set the status of accounts
GET	/workflows	List workflows
POST	/workflows/run	Run a workflow: { "workflow": "<id or name>", "profileIds": ["…"], "inputs": {} }
GET	/workflows/runs/{id}	A run and its state
GET	/tools	Capability tools your key may use
POST	/tools/{name}/run	Run one capability tool with its JSON input
POST	/mcp	MCP server (below)

Driving the browser

With the cdp scope, POST /profiles/{id}/start answers:

{
  "cdpPort": 9231,
  "wsEndpoint": "ws://127.0.0.1:9231/<token>/devtools/browser/default",
  "cdpUrl": "http://127.0.0.1:9231/<token>"
}

The browser itself has no open DevTools port: MZBase serves each profile’s endpoint on one local gateway under a random token per start. Requests from web pages (with an Origin header) and from other hosts are refused.

Connect your own automation library to cdpUrl or wsEndpoint, for example Playwright’s chromium.connectOverCDP(cdpUrl) or Puppeteer’s puppeteer.connect({ browserWSEndpoint: wsEndpoint }). Note that a library attached this way may turn on browser signals that sites detect; MZBase’s own nodes and the Browser script node use the stealth driver instead (see Workflows).

The mzb command

Terminals opened in MZBase’s Terminal page already have mzb on the PATH, with a session token for this app. Examples:

mzb profile list --search shop
mzb profile start "Shop · US 01"
mzb run "Daily check-in" --profile "Shop · US 01" --wait
mzb proxy change-ip "US residential 3"
mzb tool list

Names or ids work everywhere; --json prints the API’s JSON. Exit codes: 0 ok, 1 the app answered an error, 2 usage, 3 not in an MZBase terminal or the app is not reachable.

MCP

POST /mcp is an MCP server (streamable HTTP) with the same bearer key. AI clients see only the tools the key’s scopes allow: profiles, accounts, workflows, executions, runs, page snapshots and clicks, and every capability tool. Tools that run workflows or change many accounts can require your approval in the app before they run.

For MCP clients that only speak stdio, point them at the mzbase-mcp program installed next to the app, with the key in MZBASE_API_KEY.