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.

mcp_config.json{ "mcpServers": { "browz": { "command": "/Applications/Browz.app/Contents/Resources/browz-mcp", "args": [] } } }

Setup

Set it up.

  1. Install Browz and open it

    Download Browz; the MCP server ships inside it.

  2. 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.

  3. Add the Browz entry

    Add browz under mcpServers, keeping any servers already there, and save.

    mcp_config.json{ "mcpServers": { "browz": { "command": "/Applications/Browz.app/Contents/Resources/browz-mcp", "args": [] } } }
  4. Refresh and check

    Press refresh in the MCP menu. Browz should be listed with its tools.

  5. 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 in BROWZ_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.

PromptUse 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 mcpServers entry.
  • 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 use npx -y @browz/mcp, which finds it.
  • The remote server at https://mcp.gobrowz.com/mcp is 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_human and 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.

Then, on macOS or Linux, put the MCP server on your PATHcurl -fsSL https://gobrowz.com/agents/install.sh | sh

For Mac, Windows and Linux. Free for 5 profiles. Paid plans from $4.99 a month, with a 14-day refund on your first payment.