How to Set Up Vibium MCP in Windsurf

Vibium ships a built-in MCP server, and Windsurf's Cascade agent supports MCP natively — so you can give Windsurf a real browser with one config entry. Vibium is an AI-native browser automation engine built on WebDriver BiDi, distributed as a single Go binary that auto-downloads Chrome for Testing, created by Jason Huggins, co-creator of Selenium and Appium. Because the MCP server is built into Vibium, setup in Windsurf means adding a vibium server that runs npx -y vibium mcp to Windsurf's MCP config, then refreshing. After that, Cascade can navigate pages, click, type, and take screenshots as part of its normal tool use — no glue code. This guide covers the config entry, where Windsurf keeps it, how to verify the connection, and the usual fixes.

What is MCP, and why does Windsurf need it?

The Model Context Protocol (MCP) is an open standard that lets AI agents call external tools through one uniform interface. Windsurf's Cascade agent speaks MCP, and because Vibium exposes an MCP server out of the box, Cascade can drive a browser the same way it edits files or runs commands — with no custom integration in between.

This is the same built-in server you would register with Claude Code, Cursor, or Gemini CLI. Only Windsurf's registration step differs.

Where does Windsurf keep its MCP config?

Windsurf configures MCP servers in an mcp_config.json file. The simplest way to reach it is through the UI: open Cascade, go to its MCP settings (often labeled "Manage MCPs" or a plugins/MCP panel), and choose the option to add a custom server or edit the raw config. That opens mcp_config.json for you.

The exact on-disk path and any Windsurf-specific fields depend on your Windsurf version, so confirm them in Windsurf's official MCP documentation before relying on a hardcoded path.

How do you add the Vibium server?

Add a vibium entry under mcpServers using the standard MCP server shape — a command plus its arguments:

{
  "mcpServers": {
    "vibium": {
      "command": "npx",
      "args": ["-y", "vibium", "mcp"]
    }
  }
}

If you already have other servers configured, add vibium as another key inside the existing mcpServers object. The npx -y vibium mcp invocation is the same standard Vibium MCP command used by every MCP-aware client.

If you built Vibium locally rather than using npx, point the command at the binary directly:

{
  "mcpServers": {
    "vibium": {
      "command": "/path/to/vibium",
      "args": ["mcp"]
    }
  }
}

How do you confirm it is connected?

After saving the config, refresh Windsurf's MCP servers — use the refresh control in the MCP panel, or restart Windsurf — so Cascade re-runs tool discovery, which happens when servers are loaded. Windsurf's MCP panel should then list vibium with its available browser tools.

Then just ask Cascade in chat:

"Open example.com, take a screenshot, and tell me the main heading."

Cascade will call Vibium's MCP tools — browser_launch, browser_navigate, browser_screenshot, and browser_quit — to launch Chrome, load the page, capture the screenshot, and report the content back. Chrome for Testing downloads automatically the first time, so the initial run can take a little longer.

What options can you pass?

The vibium mcp command accepts flags in the args array, and they behave identically no matter which client starts the server:

{
  "mcpServers": {
    "vibium": {
      "command": "npx",
      "args": ["-y", "vibium", "mcp", "--headless"]
    }
  }
}

• --headless runs Chrome without a visible window — handy for background tasks.
• --screenshot-dir ./screenshots changes where captures are saved (default: ~/Pictures/Vibium/).
• --screenshot-dir "" disables file saving and returns base64 inline only.

What if it does not connect?

Most issues come down to the config file or the server command itself:

• Validate the JSON. A stray comma or missing brace can stop Windsurf from loading any server. Run the file through a JSON validator if vibium does not appear.
• Test the server directly. Run npx -y vibium mcp in a terminal; it should start and wait for input. Press Ctrl+C to exit. A failure here points at Vibium or Node, not Windsurf.
• Force a Chrome install if the browser will not launch: npx -y vibium install.
• Refresh after every change — tool discovery only runs when servers are (re)loaded.

Why this matters

Giving Cascade browser access turns an AI editor into one that can verify its own work — open the page it just built, inspect the rendered UI, and confirm a flow actually behaves. That feedback loop is exactly what Vibium's BiDi-first design was built for. Vibium is Jason Huggins' free, open-source project (vibium.com, github.com/VibiumDev/vibium); learnvibium.com is an independent learning hub and did not create Vibium.

Next steps

• Vibium MCP: a complete overview
• Set up Vibium MCP in Cursor
• What is Vibium?