Web UX Evaluator MCP server for AI agents

The MCP (Model Context Protocol) Server from operative.sh enables autonomous web application debugging by launching a browser-powered agent directly in your code editor. This tool helps evaluate and debug web applications through automated browser interactions, capturing screenshots, console logs, and network traffic.

Installation

One-Click Installation

Get your free API key from operative.sh/mcp
Use the "Add to Cursor" button provided when you create your API key for instant Cursor installation
Your API key will be automatically included in the prefilled Claude Code command

Automated Installation (macOS/Linux)

Install prerequisites (if not already installed):

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
brew install npm
brew install jq

Run the installer after getting your API key:

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

Restart your IDE to apply the changes

Test the installation by sending a prompt in chat mode:

Test my app on http://localhost:3000. Use web-eval-agent.

Manual Installation

Get your API key from operative.sh/mcp

Install UV:

curl -LsSf https://astral.sh/uv/install.sh | sh

Source your environment variables:

# Mac
source ~/.zshrc

# Linux
source ~/.bashrc

Install Playwright:

npm install -g chromium playwright && uvx --with playwright playwright install --with-deps

Add the following JSON to your code editor configuration with your API key:

"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>"
  }
}

Restart your code editor

Usage

MCP Tool Reference

The MCP Server provides two main tools:

web_eval_agent - Automated UX evaluator that drives the browser, captures screenshots, console logs, network logs, and returns a rich UX report.
setup_browser_state - Opens an interactive browser so you can sign in once; the saved cookies/local-storage are reused by subsequent web_eval_agent runs.

Key Arguments

For web_eval_agent:

url (required) - Address of the running app (e.g., http://localhost:3000)
task (required) - Natural-language description of what to test
headless_browser (optional, default: false) - Set to true to hide the browser window

For setup_browser_state:

url (optional) - Page to open first (useful for landing directly on a login screen)

Example Usage

You can trigger these tools directly from your IDE chat. For example:

Evaluate my app at http://localhost:3000 – run web_eval_agent with the task "Try the full signup flow and report UX issues".

Output Example

The MCP Server provides detailed evaluation reports like this:

📊 Web Evaluation Report for http://localhost:5173 complete!
📝 Task: Test the API-key deletion flow by navigating to the API Keys section, deleting a key, and judging the UX.

🔍 Agent Steps
  📍 1. Navigate → http://localhost:5173
  📍 2. Click     "Login"        (button index 2)
  📍 3. Click     "API Keys"     (button index 4)
  📍 4. Click     "Create Key"   (button index 9)
  📍 5. Type      "Test API Key" (input index 2)
  📍 6. Click     "Done"         (button index 3)
  📍 7. Click     "Delete"       (button index 10)
  📍 8. Click     "Delete"       (confirm index 3)
🏁 Flow tested successfully – UX felt smooth and intuitive.

Troubleshooting

Common Issues

Updates aren't being received in code editors: Run uv cache clean and then reinstall for the latest version
For static apps without changes not screencasting: Run uv clean and restart to get the fix

Updating

To update the MCP server:

uv cache clean

Then refresh the MCP server in your code editor.

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "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>"}}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "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>"
            }
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "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>"
            }
        }
    }
}

3. Restart Claude Desktop for the changes to take effect