Installation

Prerequisites

Required:

• Node.js >= 20.18.1
• Git — used to detect your project root and remote URL during initialization
• An MCP-compatible coding agent — such as Claude Code, Gemini CLI, OpenCode, Codex, Cursor, or Windsurf. See Coding Agent Setup below.

Recommended:

• Playwright — required for QA plans that include browser testing (clicking, form input, screenshot assertions, etc.). Install the Chromium binary with:

  npx playwright install chromium

  You can skip this if your QA plans only use HTTP requests. aqua will prompt you to install it if a plan requires browser steps.

Optional — Secret Providers:

If your test environments require secrets (API keys, passwords, etc.), aqua can resolve them from external secret managers. Install the CLI for the provider you use:

Provider	CLI	Install guide
1Password	op	1password.com/developers/docs/cli
AWS Secrets Manager	aws	docs.aws.amazon.com/cli
GCP Secret Manager	gcloud	cloud.google.com/sdk/docs/install
HashiCorp Vault	vault	developer.hashicorp.com/vault/install

You can also use environment variables or literal values for secrets without any external provider. See Environments for details.

1. Account Setup

Create your aqua account:

npx @aquaqa/cli login

This opens your browser for authentication. After completing the login flow, credentials are saved to ~/.aqua/credentials.json.

2. Project Setup

Run the following command inside your project repository:

npx @aquaqa/cli init

This creates a .aqua/config.json file in your project root containing:

• project_key — A unique identifier for the project, auto-detected from the git remote URL.

Once initialization is complete, subsequent CLI and MCP server commands will use this configuration automatically.

3. Coding Agent Setup

Connect aqua to the coding agent you use for development. Each agent has its own way of configuring MCP servers.

Use a dedicated session for QA

QA planning requires the agent to read through your codebase extensively — routes, business logic, edge cases, and more — to build meaningful test scenarios. This consumes a significant amount of context. We recommend running QA in a separate session from your regular development work.

Claude Code

Permanent setup

Register the aqua MCP server in your project so it is available in every session:

claude mcp add --scope project aqua -- npx @aquaqa/cli mcp-server

This creates a .mcp.json file in your project root that can be shared with your team via version control.

Also add the following to .claude/settings.json to allow aqua’s MCP tools without repeated prompts:

{
  "permissions": {
    "allow": ["mcp__aqua__*"]
  }
}

Ad-hoc session

You can also start a one-off session with the aqua MCP server without modifying any config files:

claude --mcp-config '{"mcpServers":{"aqua":{"command":"npx","args":["@aquaqa/cli","mcp-server"]}}}' --allowedTools 'mcp__aqua__*'

This is useful when you want to keep QA work isolated from your development context. Since QA planning is context-intensive, starting a fresh session for each QA cycle is recommended. Use project memory to carry knowledge across sessions.

Gemini CLI

Add aqua to your project’s Gemini CLI configuration. Create or edit .gemini/settings.json in your project root:

{
  "mcpServers": {
    "aqua": {
      "command": "npx",
      "args": ["@aquaqa/cli", "mcp-server"]
    }
  }
}

Gemini CLI will automatically start the aqua MCP server when a session begins in your project directory.

OpenCode

Add aqua to your project’s OpenCode configuration. Create or edit opencode.json in your project root:

{
  "mcp": {
    "aqua": {
      "type": "local",
      "command": ["npx", "@aquaqa/cli", "mcp-server"]
    }
  }
}

OpenCode will automatically discover and start the aqua MCP server.

Codex

Register the aqua MCP server with the codex mcp add command:

codex mcp add aqua -- npx @aquaqa/cli mcp-server

This writes the configuration to .codex/config.toml in your project. Codex will automatically start the aqua MCP server when a session begins.

You can verify the server is registered by typing /mcp in a Codex session.

Cursor

Create .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "aqua": {
      "command": "npx",
      "args": ["@aquaqa/cli", "mcp-server"]
    }
  }
}

Restart Cursor after adding the configuration. You can verify the server status in Cursor Settings > MCP.

Windsurf

Open the MCP configuration file from Cascade panel > MCP icon > Configure, or edit ~/.codeium/windsurf/mcp_config.json directly:

{
  "mcpServers": {
    "aqua": {
      "command": "npx",
      "args": ["@aquaqa/cli", "mcp-server"]
    }
  }
}

Other Agents

Any coding agent that supports MCP can use aqua. Start the MCP server with:

npx @aquaqa/cli mcp-server

The server communicates over stdio. Refer to your agent’s documentation for how to configure an MCP server connection.