GitHub - desplega-ai/qa-use: MCP server for Web UI E2E testing (original) (raw)

QA-Use MCP Server

An MCP (Model Context Protocol) server that provides comprehensive browser automation and QA testing capabilities. This server integrates with desplega.ai to offer automated testing, session monitoring, batch test execution, and intelligent test guidance using AAA (Arrange-Act-Assert) framework templates.

Modes:

QA-Use Demo

Learn more: Check out our comprehensive MCP integration guide for detailed setup instructions and advanced usage patterns.

Quick Start

Run with stdio transport (for MCP clients)

npx @desplega.ai/qa-use-mcp

Run with HTTP transport (for web/remote access)

npx @desplega.ai/qa-use-mcp --http --port 3000

Run persistent tunnel (for backend-initiated tasks)

npx @desplega.ai/qa-use-mcp tunnel

Table of Contents

MCP Client Configuration (stdio mode)

The server requires a desplega.ai API key - you can get one by using the register_user tool or by signing up at desplega.ai.

Standard configuration for most MCP clients:

{ "mcpServers": { "desplega-qa": { "command": "npx", "args": ["-y", "@desplega.ai/qa-use-mcp@latest"], "env": { "QA_USE_API_KEY": "your-desplega-ai-api-key" } } } }

Optional: Add "QA_USE_REGION": "us" to the env section to use the US region for faster tunnel connections from North America. If not set, defaults to automatic region selection.

Claude Code Use the Claude Code CLI to add the QA-Use MCP server (guide):

claude mcp add desplega-qa npx @desplega.ai/qa-use-mcp@latest --env QA_USE_API_KEY=your-desplega-ai-api-key

For US region (optional):

claude mcp add desplega-qa npx @desplega.ai/qa-use-mcp@latest --env QA_USE_API_KEY=your-desplega-ai-api-key --env QA_USE_REGION=us

Or add without environment variables and configure them later through the interactive setup:

claude mcp add desplega-qa npx @desplega.ai/qa-use-mcp@latest

Claude Desktop Add to your claude_desktop_config.json:

{ "mcpServers": { "desplega-qa": { "command": "npx", "args": ["-y", "@desplega.ai/qa-use-mcp@latest"], "env": { "QA_USE_API_KEY": "your-desplega-ai-api-key" } } } }

Cline Follow https://docs.cline.bot/mcp/configuring-mcp-servers and use the config provided above. Codex Follow the configure MCP guide using the standard config from above. You can also install the QA-Use MCP server using the Codex CLI:

codex mcp add desplega-qa -- npx @desplega.ai/qa-use-mcp@latest

Copilot / VS Code Follow the MCP install guide, with the standard config from above. You can also install the QA-Use MCP server using the VS Code CLI:

code --add-mcp '{"name":"desplega-qa","command":"npx","args":["-y","@desplega.ai/qa-use-mcp@latest"],"env":{"QA_USE_API_KEY":"your-desplega-ai-api-key"}}'

Cursor

Or install manually:

Go to Cursor Settings -> MCP -> New MCP Server. Use the config provided above.

Continue Add to your Continue config.json:

{ "mcpServers": { "desplega-qa": { "command": "npx", "args": ["-y", "@desplega.ai/qa-use-mcp@latest"], "env": { "QA_USE_API_KEY": "your-desplega-ai-api-key" } } } }

Gemini CLIInstall the QA-Use MCP server using the Gemini CLI.

Project wide:

gemini mcp add desplega-qa npx @desplega.ai/qa-use-mcp@latest

Globally:

gemini mcp add -s user desplega-qa npx @desplega.ai/qa-use-mcp@latest

Alternatively, follow the MCP guide and use the standard config from above.

Gemini Code Assist Follow the configure MCP guide using the standard config from above. JetBrains AI Assistant & Junie

Go to Settings | Tools | AI Assistant | Model Context Protocol (MCP) -> Add. Use the config provided above. The same way @desplega.ai/qa-use-mcp can be configured for JetBrains Junie in Settings | Tools | Junie | MCP Settings -> Add. Use the config provided above.

Zed Add to your Zed settings:

{ "mcpServers": { "desplega-qa": { "command": "npx", "args": ["-y", "@desplega.ai/qa-use-mcp@latest"], "env": { "QA_USE_API_KEY": "your-desplega-ai-api-key" } } } }

Your first prompt

Enter the following prompt in your MCP Client to check if everything is working:

Initialize QA server and test the login form at https://app.example.com

Your MCP client should initialize the server, set up browser automation, and start testing the specified form.

Note

The MCP server will start browser and tunnel resources automatically when needed. First-time setup requires running init_qa_server with interactive=true or providing your desplega.ai API key.

Features

HTTP Transport Mode (SSE)

In addition to the standard MCP stdio transport, QA-Use can run with StreamableHTTP transport using Server-Sent Events (SSE). This mode implements the official MCP Streamable HTTP specification and is useful for web-based integrations, remote access, or when you need HTTP-based MCP connectivity.

When to Use Each Mode

Feature stdio (default) HTTP/SSE Tunnel
Use Case Local MCP clients (Claude Desktop, Cline, etc.) Web apps, remote access, API integrations Backend-initiated tasks, CI/CD
Setup Configured in MCP client settings Start server, connect via HTTP Single command, auto-registers
Authentication Via environment variables Bearer token on each request Via environment variables
Network Local process only Can be exposed remotely Tunneled to backend
Protocol Native MCP stdio MCP over HTTP with SSE WebSocket via localtunnel
Browser On-demand On-demand Persistent with heartbeat
Best For Desktop IDE integrations Microservices, web dashboards, custom clients Backend-controlled testing, CI/CD pipelines

Starting the HTTP Server

Run the server with the --http or --api flag:

Default port (3000)

npx @desplega.ai/qa-use-mcp --http

Custom port

npx @desplega.ai/qa-use-mcp --http --port 8080

Show help

npx @desplega.ai/qa-use-mcp --help

Authentication

All MCP endpoints (except /health) require authentication via Bearer token with a valid desplega.ai API key:

Establish SSE connection

curl -N -H "Authorization: Bearer YOUR_API_KEY"
http://localhost:3000/mcp

Get your API key by:

MCP Endpoints

This server implements the MCP Streamable HTTP transport specification:

Health Check

GET /health

No authentication required

Returns server status and version

MCP Protocol Endpoint

Establish SSE connection for receiving messages

GET /mcp Headers: Authorization: Bearer YOUR_API_KEY

Send JSON-RPC messages to the server

POST /mcp Headers: Authorization: Bearer YOUR_API_KEY Content-Type: application/json Body: JSON-RPC 2.0 message

Close session

DELETE /mcp Headers: Authorization: Bearer YOUR_API_KEY MCP-Session-ID:

Example Usage

Initialize MCP Connection

Start SSE stream in one terminal

curl -N -H "Authorization: Bearer YOUR_API_KEY"
http://localhost:3000/mcp

In another terminal, send initialize message

curl -X POST http://localhost:3000/mcp
-H "Authorization: Bearer YOUR_API_KEY"
-H "Content-Type: application/json"
-d '{ "jsonrpc": "2.0", "id": 1, "method": "initialize", "params": { "protocolVersion": "2024-11-05", "capabilities": {}, "clientInfo": { "name": "test-client", "version": "1.0.0" } } }'

Call MCP Tools

List available tools

curl -X POST http://localhost:3000/mcp
-H "Authorization: Bearer YOUR_API_KEY"
-H "Content-Type: application/json"
-d '{ "jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": {} }'

Start automated test session

curl -X POST http://localhost:3000/mcp
-H "Authorization: Bearer YOUR_API_KEY"
-H "Content-Type: application/json"
-d '{ "jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": { "name": "start_automated_session", "arguments": { "task": "Test login functionality" } } }'

MCP Client Support

Any MCP client that supports the StreamableHTTP transport can connect to this server. You'll need to:

  1. Configure the client with the HTTP endpoint: http://localhost:3000/mcp
  2. Add authentication header: Authorization: Bearer YOUR_API_KEY
  3. The client will automatically handle SSE streams and JSON-RPC messaging

Note: Most current MCP clients (Claude Desktop, Cline, etc.) use stdio transport by default. The HTTP mode is primarily for:

Security Considerations

When running in HTTP mode:

Example nginx configuration for HTTPS:

server { listen 443 ssl; server_name qa-mcp.example.com;

ssl_certificate /path/to/cert.pem;
ssl_certificate_key /path/to/key.pem;

location / {
    proxy_pass http://localhost:3000;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection 'upgrade';
    proxy_set_header Host $host;
    proxy_cache_bypass $http_upgrade;

    # Required for SSE
    proxy_buffering off;
    proxy_read_timeout 24h;
}

}

Docker Deployment

The HTTP mode is perfect for containerized deployments. Example Dockerfile:

FROM node:18-slim

Install dependencies for Playwright

RUN apt-get update && apt-get install -y
libnss3 libatk-bridge2.0-0 libdrm2 libxkbcommon0
libgbm1 libasound2 libxshmfence1
&& rm -rf /var/lib/apt/lists/*

Install qa-use-mcp

RUN npm install -g @desplega.ai/qa-use-mcp

Expose port

EXPOSE 3000

Set API key via environment variable

ENV QA_USE_API_KEY=your-api-key-here

Start in HTTP mode

CMD ["qa-use-mcp", "--http", "--port", "3000"]

Run the container:

docker build -t qa-use-mcp . docker run -d -p 3000:3000
-e QA_USE_API_KEY=your-api-key
qa-use-mcp

Vercel Deployment

Deploy to Vercel for serverless hosting:

Deploy with Vercel

Quick setup:

Install Vercel CLI

npm i -g vercel

Deploy

vercel --prod

Vercel Build Settings:

Environment Variables (set in Vercel dashboard):

⚠️ Important: Vercel has execution time limits (60s max on Pro plan) which may affect long-running SSE connections. For production use with long-running sessions, consider:

See VERCEL_DEPLOYMENT.md for detailed deployment guide and limitations.

Backward Compatibility

All modes are fully backward compatible. Running without flags uses the standard MCP stdio transport:

Standard MCP mode (stdio) - default

npx @desplega.ai/qa-use-mcp

HTTP transport mode (SSE)

npx @desplega.ai/qa-use-mcp --http

Tunnel mode (persistent WebSocket)

npx @desplega.ai/qa-use-mcp tunnel

All modes support the complete MCP tools and functionality. The HTTP mode follows the official MCP Streamable HTTP specification.

Tunnel Mode

The tunnel mode creates a persistent WebSocket tunnel that allows the desplega.ai backend to initiate browser automation tasks using your local browser. This is perfect for scenarios where you want the backend to control test execution while using your local environment's browser.

When to Use Tunnel Mode

Scenario Best Mode
Backend-initiated tests Tunnel ✅
CI/CD pipelines with local browsers Tunnel ✅
Remote test execution on local environment Tunnel ✅
Interactive MCP client testing stdio
Web dashboard integrations HTTP/SSE

How It Works

  1. Start Tunnel: Creates a Playwright browser and localtunnel
  2. Register WebSocket: Sends the tunneled WebSocket URL to desplega.ai backend
  3. Heartbeat: Sends keepalive signals every 5 seconds to maintain the connection
  4. Backend Control: Backend can now initiate test sessions using your local browser

Starting Tunnel Mode

Start tunnel with headless browser (default)

npx @desplega.ai/qa-use-mcp tunnel

Start tunnel with visible browser

npx @desplega.ai/qa-use-mcp tunnel --visible

Example Output

🔧 QA-Use Tunnel Mode
====================
Mode: Headless

🔑 Validating API key...
✅ API key valid

🌐 Starting browser tunnel...
✅ Browser started
✅ Tunnel created

📡 WebSocket URL: wss://qa-use-123456.lt.desplega.ai/...
✅ Registered with backend

🔄 Heartbeat active (every 5s)
   Press Ctrl+C to stop

[10:30:15] ✓ Heartbeat #1 sent
[10:30:20] ✓ Heartbeat #2 sent
[10:30:25] ✓ Heartbeat #3 sent

Environment Variables

Set your API key before starting tunnel mode:

export QA_USE_API_KEY=your-desplega-ai-api-key npx @desplega.ai/qa-use-mcp tunnel

Optionally configure the US region for better tunnel performance from North America:

export QA_USE_API_KEY=your-desplega-ai-api-key export QA_USE_REGION=us npx @desplega.ai/qa-use-mcp tunnel

Alternatively, you can use a config file instead of environment variables. See Configuration File for details.

Options

Use Cases

1. CI/CD Integration

Run tunnel mode in your CI/CD pipeline to allow backend-initiated tests:

.github/workflows/qa.yml

2. Development Testing

Keep a tunnel running while developing to allow ad-hoc tests from the backend:

Terminal 1: Keep tunnel running

npx @desplega.ai/qa-use-mcp tunnel

Terminal 2: Trigger tests from backend via API/dashboard

The backend will use your local browser through the tunnel

3. Debugging with Visible Browser

When you need to see what's happening:

npx @desplega.ai/qa-use-mcp tunnel --visible

Graceful Shutdown

Press Ctrl+C to stop the tunnel. The server will:

  1. Stop sending heartbeats
  2. Close the tunnel
  3. Shutdown the browser
  4. Clean up resources

Differences from Other Modes

Feature stdio HTTP/SSE Tunnel
Control Local MCP client HTTP requests Backend-initiated
Browser On-demand On-demand Persistent
Heartbeat N/A N/A Every 5s
Use Case Desktop IDEs Web apps Backend tasks
Visibility Configurable Configurable Headless default

Installation

Install and run directly with npx:

npx @desplega.ai/qa-use-mcp

Or install globally:

npm install -g @desplega.ai/qa-use-mcp qa-use-mcp # or: desplega-qa

Development

Clone the repository and install dependencies:

git clone cd qa-use-mcp pnpm install

Build the project:

Start the development server:

MCP Tools

The server exposes the following MCP tools for browser automation and QA testing:

Setup & Configuration

ensure_installed

Ensure API key is set, validate authentication, and install Playwright browsers.

Parameters:

register_user

Register a new user account with desplega.ai and receive an API key.

Parameters:

update_configuration

Update application configuration settings including base URL, login credentials, and viewport type.

Parameters:

get_configuration

Get the current application configuration details including base URL, login settings, and viewport.

Parameters: None

Session Management

search_sessions

Search and list all sessions (automated tests and development sessions) with pagination and filtering.

Parameters:

start_automated_session

Start an automated E2E test session for QA flows and automated testing. Returns sessionId for monitoring.

Parameters:

start_dev_session

Start an interactive development session for debugging and exploration. Session will not auto-pilot and allows manual browser interaction.

Parameters:

monitor_session

Monitor a session status. Keep calling until status is "closed". Will alert if session needs user input, is idle, or pending.

Parameters:

interact_with_session

Interact with a session - respond to questions, pause, or close the session.

Parameters:

Test Management

search_automated_tests

Search for automated tests by ID or query. If testId provided, returns detailed info for that test. Otherwise searches with optional query/pagination.

Parameters:

run_automated_tests

Execute multiple automated tests simultaneously.

Parameters:

search_automated_test_runs

Search automated test runs with optional filtering by test ID or run ID.

Parameters:

Built-in Documentation

The server includes comprehensive MCP resources and prompts:

MCP Resources

MCP Prompts

Configuration

Environment Variables

Create a .env file in your project root or set the following environment variables:

Required: Your desplega.ai API key

QA_USE_API_KEY=your-desplega-ai-api-key

Optional: Region selection for tunnel and API routing

Values: "us" | "auto"

Default: "auto" (if not set)

- "us": Uses lt.us.desplega.ai for localtunnel and routes to US region

- "auto": Uses default lt.desplega.ai and automatic region routing

QA_USE_REGION=us

Optional: Custom API endpoint (default: https://api.desplega.ai)

QA_USE_API_URL=https://api.desplega.ai

Optional: Custom app URL (default: https://app.desplega.ai)

QA_USE_APP_URL=https://app.desplega.ai

Optional: Custom tunnel host (overrides QA_USE_REGION setting)

TUNNEL_HOST=https://lt.desplega.ai

Regional Configuration

The QA_USE_REGION variable allows you to route your tunnel and API requests to specific regions:

Example configuration for US region:

export QA_USE_API_KEY=your-api-key export QA_USE_REGION=us npx @desplega.ai/qa-use-mcp

Note: If QA_USE_REGION is not set, the system automatically defaults to "auto" behavior.

Configuration File

As an alternative to environment variables, you can store your configuration in ~/.qa-use.json:

{ "env": { "QA_USE_API_KEY": "your-api-key-here", "QA_USE_API_URL": "https://api.desplega.ai", "QA_USE_APP_URL": "https://app.desplega.ai", "QA_USE_REGION": "us" } }

Priority order:

  1. Environment variables (highest priority)
  2. Config file (~/.qa-use.json)
  3. Default values

This is useful when you don't want to set environment variables or when using MCP clients that don't support environment configuration.

An example config file is available at .qa-use.example.json in this repository.

Usage Examples

Interactive Testing Workflow

1. Initialize server and install browsers

ensure_installed

2. Configure app settings (one-time setup)

update_configuration with base_url="https://app.example.com" and login_url="https://app.example.com/login" and login_username="testuser@example.com"

3. Start an automated test session

start_automated_session with task="Test user registration flow"

4. Monitor session progress

monitor_session with sessionId="session-123" and wait=true and timeout=300

5. Interact with session if needed (respond, pause, or close)

interact_with_session with sessionId="session-123" and action="respond" and message="john.doe@example.com"

Development & Debugging Workflow

1. Start an interactive dev session (no auto-pilot)

start_dev_session with task="Exploring the checkout flow" and url="https://app.example.com/cart"

2. Monitor and interact as needed

monitor_session with sessionId="dev-session-456"

3. Close when done

interact_with_session with sessionId="dev-session-456" and action="close"

Batch Testing Workflow

1. Find available tests

search_automated_tests with query="login" and limit=10

2. Run multiple tests simultaneously

run_automated_tests with test_ids=["login-test-1", "signup-test-2", "checkout-test-3"]

3. Monitor progress

search_sessions with limit=20

4. Check test run history

search_automated_test_runs with limit=50

Using AAA Framework Template

Generate a structured test using AAA framework

Use prompt: aaa_test with test_type="login" and url="https://app.example.com/login" and feature="user authentication"

Resource Management

When you hit the 10 session limit or need to free up resources

reset_browser_sessions

This will clean up all active browsers and tunnels

Useful when sessions aren't closing properly or you need to restart fresh

Testing

Use the provided test scripts to test MCP server functionality:

Test server initialization (uses env var if available)

./scripts/test-init.sh

Test listing sessions

./scripts/test-list-sessions.sh

Test starting a session

./scripts/test-start-session.sh

Test with real API key from environment

node scripts/mcp-test.js

Architecture

The project is organized into modular components:

Key Features Implementation

MCP Timeout Protection

AAA Framework Integration

Test Analytics

License

MIT