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.

MCP Client Configuration

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

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

Or add without the API key and configure it 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 CLI

Install 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

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

Browser Management: Launch and control Playwright browser instances with headless/headed modes
Tunneling: Create public tunnels for browser WebSocket endpoints using localtunnel
API Integration: Full integration with desplega.ai API for comprehensive QA testing workflows
Session Management: Create, monitor, and control multiple QA testing sessions with real-time status
- Smart session lifecycle management with automatic cleanup
- Up to 10 concurrent browser sessions with clear error handling
- 30-minute default TTL with automatic deadline refresh on interaction
- Background cleanup task for expired sessions
Progress Monitoring: Real-time progress notifications with MCP timeout protection (25s max per call)
Batch Test Execution: Run multiple automated tests simultaneously with dependency management
Interactive Elicitation: Intelligent prompts when remote sessions need user input to continue
Test Discovery: Search and list automated tests with pagination and filtering
Test Run Analytics: View test execution history with performance metrics and flakiness scores
AAA Framework Templates: Pre-built prompts for login, forms, e-commerce, navigation, and comprehensive testing scenarios
User Registration: Built-in user registration system for new desplega.ai accounts
Comprehensive Documentation: Built-in MCP resources with guides, workflows, and best practices

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 <repository-url>
cd qa-use-mcp
pnpm install

Build the project:

pnpm build

Start the development server:

pnpm dev

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:

apiKey (string, optional): API key for desplega.ai (optional if QA_USE_API_KEY env var is set)

`register_user`

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

Parameters:

email (string, required): Email address for registration

`update_configuration`

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

Parameters:

base_url (string, optional): Base URL for the application being tested
login_url (string, optional): Login page URL for the application
login_username (string, optional): Default username for login testing
login_password (string, optional): Default password for login testing
vp_type (string, optional): Viewport configuration type: big_desktop, desktop, mobile, or tablet (default: desktop)

`get_configuration`

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

Parameters: None

`reset_browser_sessions`

Reset and cleanup all active browser sessions. This will kill all browsers and tunnels. Use this when you hit the maximum session limit or need to free up resources.

Parameters: None

Session Management

`search_sessions`

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

Parameters:

limit (number, optional): Maximum number of sessions to return (default: 10, min: 1)
offset (number, optional): Number of sessions to skip (default: 0, min: 0)
query (string, optional): Search query to filter sessions by task, URL, or status

`start_automated_session`

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

Parameters:

task (string, required): The testing task or scenario to execute
url (string, optional): Optional URL to test (overrides app config base_url if provided)
dependencyId (string, optional): Optional test ID that this session depends on (must be a self test ID created by your app configuration)
headless (boolean, optional): Run browser in headless mode (default: false for better visibility)

`start_dev_session`

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

Parameters:

task (string, required): Description of what you want to explore or debug. Can be a placeholder like "Waiting for user input"
url (string, optional): Optional URL to start from (overrides app config base_url if provided)
headless (boolean, optional): Run browser in headless mode (default: false for development visibility)

`monitor_session`

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

Parameters:

sessionId (string, required): The session ID to monitor
wait (boolean, optional): Wait for session to reach any non-running state with MCP timeout protection (max 25s per call)
timeout (number, optional): User timeout in seconds for wait mode (default: 60)

`interact_with_session`

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

Parameters:

sessionId (string, required): The session ID to interact with
action (string, required): Action to perform: respond (answer question), pause (stop session), or close (end session)
message (string, optional): Your response message (required for "respond" action, optional for others)

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:

testId (string, optional): Specific test ID to retrieve detailed information for (if provided, other params ignored)
query (string, optional): Search query to filter tests by name, description, URL, or task (ignored if testId provided)
limit (number, optional): Maximum number of tests to return (default: 10, min: 1) (ignored if testId provided)
offset (number, optional): Number of tests to skip (default: 0, min: 0) (ignored if testId provided)
self_only (boolean, optional): Filter tests by app configuration. When true, only returns tests created by your application configuration. Default: false to allow running tests from other configs locally.

`run_automated_tests`

Execute multiple automated tests simultaneously.

Parameters:

test_ids (array, required): Array of test IDs to execute
app_config_id (string, optional): Optional app config ID to run tests against (uses API key default config if not provided)
ws_url (string, optional): Optional WebSocket URL override (uses global tunnel URL by default)

`search_automated_test_runs`

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

Parameters:

test_id (string, optional): Filter test runs by specific test ID
run_id (string, optional): Filter test runs by specific run ID
limit (number, optional): Maximum number of test runs to return (default: 10, min: 1)
offset (number, optional): Number of tests to skip (default: 0, min: 0)

Built-in Documentation

The server includes comprehensive MCP resources and prompts:

MCP Resources

Getting Started Guide: Complete setup and usage instructions
Testing Workflows: Common patterns for interactive, batch, and development testing
Tool Reference: Detailed documentation for all available MCP tools

MCP Prompts

aaa_test: Generate structured test scenarios using the Arrange-Act-Assert (AAA) framework with customizable parameters

Configuration

Environment Variables

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

QA_USE_API_KEY=your-desplega-ai-api-key

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:

src/: Main MCP server implementation with comprehensive tool handlers
- MCP protocol implementation with tools, resources, and prompts
- Session management and monitoring with timeout protection
- BrowserSession management with automatic lifecycle tracking
  - Each session wraps browser + tunnel with TTL and deadline tracking
  - Session types: 'dev', 'automated', and 'test_run'
  - Automatic cleanup on expiration or completion
- Real-time progress notifications using MCP logging specification
- AAA framework prompt templates for structured testing
lib/browser/: Browser management functionality using Playwright
- Headless and headed browser support
- WebSocket endpoint management for remote control
lib/tunnel/: Tunneling and port forwarding using localtunnel
- Public tunnel creation for browser WebSocket access
- Automatic WebSocket URL conversion for remote testing
lib/api/: Complete API client for desplega.ai integration
- Session lifecycle management (create, monitor, respond)
- Test discovery and execution
- Test run analytics and history
- User registration and authentication
- Batch test execution with dependency handling

Key Features Implementation

MCP Timeout Protection

Limited monitoring calls to 25 seconds to prevent MCP timeouts
Automatic continuation support for long-running sessions
Real-time progress notifications during session monitoring

AAA Framework Integration

Pre-built templates for login, forms, e-commerce, and navigation testing
Comprehensive test scenarios for accessibility, performance, and mobile testing
Dynamic argument support for customizable test generation

Test Analytics

Complete test run history with performance metrics
Probabilistic Flakiness Score (PFS) tracking
Execution timing and error tracking
Filtering and pagination for large datasets

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 40 Commits
lib		lib
scripts		scripts
src		src
.gitignore		.gitignore
.prettierrc		.prettierrc
CONTRIBUTING.md		CONTRIBUTING.md
IDEAS.md		IDEAS.md
LICENSE		LICENSE
Makefile		Makefile
PLAN.md		PLAN.md
PRD.md		PRD.md
README.md		README.md
eslint.config.js		eslint.config.js
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
server.json		server.json
test-connection.js		test-connection.js
test-watch.txt		test-watch.txt
tsconfig.json		tsconfig.json

License

desplega-ai/qa-use

Folders and files

Latest commit

History

Repository files navigation

QA-Use MCP Server

MCP Client Configuration

Your first prompt

Features

Installation

Development

MCP Tools

Setup & Configuration

ensure_installed

register_user

update_configuration

get_configuration

reset_browser_sessions

Session Management

search_sessions

start_automated_session

start_dev_session

monitor_session

interact_with_session

Test Management

search_automated_tests

run_automated_tests

search_automated_test_runs

Built-in Documentation

MCP Resources

MCP Prompts

Configuration

Environment Variables

Usage Examples

Interactive Testing Workflow

Development & Debugging Workflow

Batch Testing Workflow

Using AAA Framework Template

Resource Management

Testing

Architecture

Key Features Implementation

MCP Timeout Protection

AAA Framework Integration

Test Analytics

License

About

Topics

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Contributors 2

Uh oh!

Languages

`ensure_installed`

`register_user`

`update_configuration`

`get_configuration`

`reset_browser_sessions`

`search_sessions`

`start_automated_session`

`start_dev_session`

`monitor_session`

`interact_with_session`

`search_automated_tests`

`run_automated_tests`

`search_automated_test_runs`