How to add web-eval-agent to Windsurf

Autonomous browser agent that evaluates and debugs your web app end-to-end from your IDE. Paste the config into ~/.codeium/windsurf/mcp_config.json and restart Windsurf.

Last updated June 14, 2026 · 1.2k★ · stdio · apikey · official

Windsurf config for web-eval-agent

curl -LSf https://operative.sh/install.sh -o install.sh && bash install.sh && rm install.sh

{
  "mcpServers": {
    "web-eval-agent": {
      "command": "uvx",
      "args": [
        "--refresh-package",
        "webEvalAgent",
        "--from",
        "git+https://github.com/Operative-Sh/web-eval-agent.git",
        "webEvalAgent"
      ],
      "env": {
        "OPERATIVE_API_KEY": "<YOUR_KEY>"
      }
    }
  }
}

Requires `uv` (the Python package runner). Install it from https://docs.astral.sh/uv/ if `uvx` is not found.

Setup steps

1Open Windsurf → Cascade → the hammer/MCP icon → Configure (or edit ~/.codeium/windsurf/mcp_config.json).
2Paste the web-eval-agent config below.
3Fill in placeholder secrets, then save.
4Click Refresh in the MCP panel.
5web-eval-agent's tools become available to Cascade.

Before you start

A free OPERATIVE_API_KEY from operative.sh/mcp
uv (installed via curl -LsSf https://astral.sh/uv/install.sh | sh)
Playwright with Chromium (npm install -g chromium playwright && uvx --with playwright playwright install --with-deps)
A running web app to evaluate (e.g. http://localhost:3000)

What web-eval-agent can do in Windsurf

web_eval_agent

Automated UX evaluator that drives the browser to perform a natural-language task, captures screenshots, console & network logs, and returns a rich UX report. Required args: url (address of the running app, e.g. http://localhost:3000) and task (what to test). Optional: headless_browser (default false; set true to hide the browser window).

setup_browser_state

Opens an interactive (non-headless) browser so you can sign in once; the saved cookies/local-storage are reused by subsequent web_eval_agent runs. Optional arg: url (page to open first, handy to land directly on a login screen).

Security

Requires a free OPERATIVE_API_KEY from operative.sh/mcp, passed via the env block. The agent drives a real browser against your running app and can sign in via setup_browser_state, which persists cookies and local-storage locally for reuse. Note: this project has been discontinued by its maintainers.

web-eval-agent + Windsurf FAQ

Where is the Windsurf config file?

Windsurf reads MCP servers from ~/.codeium/windsurf/mcp_config.json. Paste the web-eval-agent config there under the "mcpServers" key and restart the client.

Is web-eval-agent safe to use with Windsurf?

Is this project still maintained?

No. The README states the project has been sunset/discontinued; the maintainers are building something new at withrefresh.com.

How do I get an API key?

Get a free API key at operative.sh/mcp. When you create it you also get an 'Add to Cursor' deeplink and a prefilled Claude Code command with the key included.

Updates aren't showing up in my editor. What do I do?

Run `uv cache clean` and refresh/restart the MCP server in your code editor to pull the latest version.

View repo Full web-eval-agent page