WaveXis MCP Agent Integration

Description

wavexis-mcp is an MCP (Model Context Protocol) server that exposes 220 tools for LLM-driven browser automation. It wraps wavexis (which wraps cdpwave + bidiwave) and provides 13 capability tiers so LLMs can control browsers with natural language, take screenshots, scrape content, fill forms, run performance audits, and execute multi-step workflows — all through structured tool calls.

When to Invoke

• Configuring wavexis-mcp in an IDE or MCP client (Claude, Cursor, Windsurf, VS Code)
• Choosing capability tiers for a specific use case
• Managing browser sessions (open, close, list, switch)
• Using natural language interaction (wavexis_act) for form filling and clicks
• Creating multi-action YAML workflows via MCP
• Debugging MCP connection issues or tool errors
• Understanding the 220-tool catalog and tier system
• Setting up stateless vs session mode
• Configuring rate limiting, stealth mode, or SSRF protection

1. Installation

Install

pip install wavexis-mcp[cdp]

Run without installing

uvx wavexis-mcp --caps all

Verify

wavexis-mcp --version

2. IDE Configuration

Claude Desktop

Edit claude_desktop_config.json:

{
  "mcpServers": {
    "wavexis": {
      "command": "uvx",
      "args": ["wavexis-mcp", "--caps", "all"]
    }
  }
}

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "wavexis": {
      "command": "uvx",
      "args": ["wavexis-mcp", "--caps", "core,network,storage"]
    }
  }
}

Windsurf

Add to MCP settings:

{
  "mcpServers": {
    "wavexis": {
      "command": "uvx",
      "args": ["wavexis-mcp", "--caps", "all"]
    }
  }
}

VS Code (Copilot)

Add to .vscode/mcp.json:

{
  "servers": {
    "wavexis": {
      "command": "uvx",
      "args": ["wavexis-mcp", "--caps", "core,devtools,a11y"]
    }
  }
}

HTTP transport (remote)

wavexis-mcp --transport http --host 0.0.0.0 --port 8765 --caps all

Then configure the client with the URL:

{
  "mcpServers": {
    "wavexis": {
      "url": "http://localhost:8765"
    }
  }
}

3. Capability Tiers

13 tiers from core (always on, 72 tools) to all (220 tools). Select tiers with --caps:

# All 220 tools
wavexis-mcp --caps all

# Core only (72 tools — minimal, saves tokens)
wavexis-mcp --caps core

# Core + network + storage (110 tools — common scraping setup)
wavexis-mcp --caps core,network,storage

# Core + devtools + a11y (107 tools — debugging + accessibility)
wavexis-mcp --caps core,devtools,a11y

# Everything except experimental (189 tools)
wavexis-mcp --caps core,network,storage,emulation,a11y,interactions,devtools,vision,video,testing,workflows,data

Tier Catalog

Tier Selection Guide

4. Session Management

wavexis-mcp supports two modes: session and stateless.

Session mode (default)

Open a persistent browser session, execute multiple tool calls, then close:

1. wavexis_session_open          → session_id
2. wavexis_navigate(url)          → uses session
3. wavexis_screenshot()           → uses session
4. wavexis_eval(expression)       → uses session
5. wavexis_session_close          → cleanup

Benefits:

• Browser stays open between tool calls
• State preserved (cookies, localStorage, page position)
• Multi-step workflows in a single browser instance
• Faster (no browser launch per call)

Stateless mode

Each tool call opens and closes a browser:

1. wavexis_screenshot(url)        → opens browser, captures, closes
2. wavexis_scrape(url)            → opens browser, scrapes, closes

Benefits:

• No session management overhead
• Each call is independent
• Simpler for one-off tasks

Session tools

Best practices

• Always close sessions — Unclosed sessions leak resources
• One session per workflow — Don't interleave sessions
• Use stateless for one-offs — No cleanup needed
• List sessions to debug — wavexis_session_list shows active sessions

5. Core Tools (72 — always available)

Navigation

Capture

Evaluate

Input

Cookies

Natural Language

Advanced DOM

Events

Console

Browser info

6. Natural Language Interaction

wavexis_act lets LLMs control browsers using natural language instead of CSS selectors:

User: "Click the login button"
→ wavexis_act(action="click", description="the login button")

User: "Fill the email field with admin@example.com"
→ wavexis_act(action="fill", description="the email field", text="admin@example.com")

User: "Find the submit button"
→ wavexis_find(description="the submit button")

Supported actions

How it works

1. LLM calls wavexis_act with a natural language description
2. wavexis-mcp analyzes the page DOM
3. Matches the description to the most likely element
4. Executes the action
5. Returns the result and element info

This eliminates the need for LLMs to know CSS selectors, making browser automation accessible through plain language.

7. Multi-Action Workflows

Chain multiple actions in a single tool call using YAML:

wavexis_multi(config="""
actions:
  - navigate: https://example.com/login
  - fill:
      selector: "#username"
      text: admin@example.com
  - fill:
      selector: "#password"
      text: changeme
  - click:
      selector: "#submit"
  - wait_for:
      selector: ".dashboard"
      timeout: 10000
  - screenshot:
      full_page: true
""")

Workflow tools

8. Network Tools (tier: network)

9. DevTools Tools (tier: devtools)

10. Data Tools (tier: data)

11. Testing Tools (tier: testing)

12. Configuration Options

CLI flags

Environment variables

13. Error Handling

wavexis-mcp returns structured errors with actionable suggestions:

{
  "error": {
    "code": "SESSION_NOT_FOUND",
    "message": "Session abc123 not found",
    "suggestion": "Call wavexis_session_open to create a new session, or check wavexis_session_list for active sessions"
  }
}

Common error codes

14. Security

SSRF protection

wavexis-mcp blocks requests to private IP ranges by default:

• 10.0.0.0/8
• 172.16.0.0/12
• 192.168.0.0/16
• 127.0.0.0/8
• 169.254.0.0/16
• ::1/128

Rate limiting

wavexis-mcp --rate-limit 60

60 requests per minute per client. Excess requests return RATE_LIMIT_EXCEEDED.

Stealth mode

wavexis-mcp --stealth

Hides navigator.webdriver, fakes browser fingerprints. Useful for scraping protected sites.

Remote access

wavexis-mcp --transport http --host 0.0.0.0 --port 8765 --allow-remote

Warning: Only use --allow-remote behind a reverse proxy with authentication.

15. Docker

Pull and run

docker run -p 8765:8765 ghcr.io/mathiaspaulenko/wavexis-mcp:latest \
  --transport http --caps all

Docker Compose

version: "3.8"
services:
  wavexis-mcp:
    image: ghcr.io/mathiaspaulenko/wavexis-mcp:latest
    ports:
      - "8765:8765"
    command: --transport http --caps all --host 0.0.0.0
    environment:
      - WAVEXIS_MCP_RATE_LIMIT=60
    restart: unless-stopped

16. MCP Resources and Prompts

wavexis-mcp also exposes MCP resources and prompts beyond tools:

Resources

Prompts

17. Best Practices

• Start with core tier — 72 tools covers most use cases. Add tiers as needed to save tokens
• Always close sessions — Call wavexis_session_close when done to avoid resource leaks
• Use wavexis_act for forms — Natural language is more robust than selectors for form filling
• Use multi-action YAML — Chain actions in a single call to reduce round trips
• Enable stealth for scraping — --stealth hides automation indicators
• Set rate limits — Prevent runaway LLM agents from making too many calls
• Use HTTP transport for teams — Deploy in Docker with --transport http for shared access
• Check wavexis_session_list — Debug stuck sessions by listing active ones
• Use wavexis_find before wavexis_click — NL element finding is more reliable than guessing selectors
• Leverage assertions for testing — wavexis_assert_* tools provide pass/fail results for CI

18. Common Pitfalls

19. References

• references/tool-catalog.md — Complete 220-tool catalog with parameters and return types
• references/tier-selection.md — Detailed tier selection guide with use-case scenarios
• references/ide-setup-guide.md — Step-by-step IDE configuration for Claude, Cursor, Windsurf, VS Code
• assets/mcp-configs/claude-desktop.json — Claude Desktop config template
• assets/mcp-configs/cursor.json — Cursor config template
• assets/mcp-configs/windsurf.json — Windsurf config template
• assets/mcp-configs/vscode.json — VS Code config template
• assets/mcp-configs/http-remote.json — HTTP transport remote config template
• Related skills: wave-ecosystem-guide, wavexis-cli-automation, wavexis-web-scraping, wavexis-performance-audit