Integrations / AI agent clients / Windsurf (Cascade)
A browser for Cascade, kept apart from yours.
Cascade, the agent in the Windsurf editor, can call MCP tools. Add Browz and it can check your app in a real browser, step through sign-in and forms as a test user, and report back with screenshots, each task in an isolated profile.
{
"mcpServers": {
"browz": {
"command": "/Applications/Browz.app/Contents/Resources/browz-mcp",
"args": []
}
}
}Setup
Set it up.
Install Browz and open it
Download Browz; the MCP server ships inside it.
Open Cascade’s MCP config
In the Cascade panel, open the MCP menu and choose Open MCP config file. It opens
mcp_config.json, wherever your version keeps it.Add the Browz entry
Add
browzundermcpServers, keeping any servers already there, and save.mcp_config.json{ "mcpServers": { "browz": { "command": "/Applications/Browz.app/Contents/Resources/browz-mcp", "args": [] } } }Refresh and check
Press refresh in the MCP menu. Browz should be listed with its tools.
Remote (beta)
Cascade reads environment variables with
${env:NAME}, so an agent token can stay out of the file. Create the token on your account page and put it inBROWZ_AGENT_TOKEN.mcp_config.json, remote{ "mcpServers": { "browz": { "serverUrl": "https://mcp.gobrowz.com/mcp", "headers": { "Authorization": "Bearer ${env:BROWZ_AGENT_TOKEN}" } } } }
Config format from Cascade MCP docs.
Example
Check a form after a change.
After Cascade edits a form, ask it to try the form in a real browser and show you the result.
Use the Browz MCP tools: open a throwaway session for "contact form", go to http://localhost:5173/contact, fill the form with test data, submit it, take a screenshot of the result and close the session.Good to know
Notes and tips.
- Windsurf’s documentation now lives with Devin, and the editor’s menus may be named differently in your version; the config format is the same
mcpServersentry. - The snippets use the macOS path of the server inside Browz. On Windows it is
%LOCALAPPDATA%\Programs\Browz\browz-mcp.exe, on Linux/usr/lib/browz/browz-mcp; or usenpx -y @browz/mcp, which finds it. - The remote server at
https://mcp.gobrowz.com/mcpis in free public beta: it needs the Browz app open with Remote control on, on a computer with a hardware security chip, and offers the profile, tab and page tools. See what it needs and what it offers. - Browz has to be installed and open on the same computer: the local MCP server drives the app’s own profiles through its local API, and reads the app’s credentials itself, so no token goes in the config.
- A person completes sign-ins, 2FA codes and CAPTCHAs. The agent can pause with
browz_request_humanand hand you the profile’s window, then carry on in the same session. Browz never solves or bypasses CAPTCHAs. - Use agents only where each site’s terms allow automated use, on accounts you are entitled to use. Our acceptable use policy applies to agents the same as to people.
- The MCP server is on every plan, Free included (5 profiles). How many agent sessions can be open at once depends on the plan: see pricing.
FAQ
Windsurf (Cascade) and Browz.
Where is mcp_config.json?
Open it from Cascade’s MCP menu (Open MCP config file). Its location depends on the version of the editor, so the menu is the reliable way.
Can I limit what Cascade can do in Browz?
Yes. Give the server its own local agent key, limited to the profiles and sites it needs, and pass it as BROWZ_LOCAL_AGENT_TOKEN in an env entry; lock any profile it should not open.
Does Cascade get my own cookies?
No. It works in Browz profiles only, each a separate browser with its own cookies and storage.
Get started
Download Browz. Every task, its own browser.
curl -fsSL https://gobrowz.com/agents/install.sh | sh