1. Find the API
When Browz is open, its agent listens on 127.0.0.1, port 50333 by default, and only on your computer. Every request needs the agent’s bearer token. Print it with browz --show-token status (step 4 sets up the browz command), and rotate it from the API & MCP screen in the app.
Shellexport BROWZ_TOKEN="<token from browz --show-token status>"
curl -s http://127.0.0.1:50333/api/v1/proxy/list \
-H "Authorization: Bearer $BROWZ_TOKEN"
2. Create and start a profile
Shell# create a profile
curl -s -X POST http://127.0.0.1:50333/api/v1/profile/create \
-H "Authorization: Bearer $BROWZ_TOKEN" \
-d '{"name":"Research – NYC"}'
# start it; the response includes debugPort
curl -s -X POST http://127.0.0.1:50333/api/v1/browser/start \
-H "Authorization: Bearer $BROWZ_TOKEN" \
-d '{"id":"<profile id>"}'
3. Drive it over CDP
Connect any Chrome DevTools Protocol client to 127.0.0.1:debugPort.
Playwright (Node)const browser = await chromium.connectOverCDP(
`http://127.0.0.1:${debugPort}`);
const [page] = browser.contexts()[0].pages();
await page.goto('https://example.com');
Puppeteer (Node)const browser = await puppeteer.connect({
browserURL: `http://127.0.0.1:${debugPort}` });
const [page] = await browser.pages();
await page.goto('https://example.com');
4. Use the command line
The browz command is built into the agent. Add an alias, then work with profiles by name or id. It finds the running agent by itself.
Shellalias browz="/Applications/Browz.app/Contents/Resources/browz-agent"
browz status
browz list
browz start "Research – NYC"
browz proxy add "Sydney residential" --host 203.0.113.10 --port 8080 --scheme http
browz --json list
5. Connect an AI agent over MCP
Point any MCP client at the bundled server (the paths in this guide are for Mac). It talks to the same local API with the same token, so Browz must be open.
MCP client config{
"mcpServers": {
"browz": { "command": "/Applications/Browz.app/Contents/Resources/browz-mcp" }
}
}
Full reference. The API & MCP screen in the app lists every endpoint and includes a playground for trying them. A hosted reference will follow.