MCP Tools Reference

The aqua MCP server exposes the following tools. These tools allow AI agents to create, manage, and execute QA plans programmatically.

Plan Management

Tools for creating and managing QA plans and their versions.

Tool	Description
`create_qa_plan`	Create a new QA plan. Auto-detects the current git branch and pull request URL.
`get_qa_plan`	Retrieve a plan by ID, including its latest version information.
`list_qa_plans`	List plans with optional status filter and cursor-based pagination.
`update_qa_plan`	Create a new immutable version with the full scenario and step structure. Steps support an optional `condition` field for conditional execution based on variable values.
`update_qa_plan_step`	Partial update of a single step. Creates a new plan version. Supports setting a `condition` for conditional execution.
`add_qa_plan_step`	Add a step to a scenario. Creates a new plan version. Supports setting a `condition` for conditional execution.
`remove_qa_plan_step`	Remove a step by its key. Creates a new plan version. Fails if other steps depend on it.
`set_qa_plan_status`	Change the plan status: `draft`, `active`, or `archived`.

Execution

Tools for running QA plans and inspecting results.

Tool	Description
`execute_qa_plan`	Execute a full plan and record results on the server. Returns a markdown summary and an execution URL. Supports an `async` parameter for background execution.
`run_scenario`	Execute a single inline scenario without recording results on the server. Returns detailed debug output.
`get_execution`	Fetch execution results including per-step details.
`list_executions`	List executions filtered by plan ID, version, or status.
`get_execution_progress`	Get the current progress of a running execution. Use this to monitor async executions started with `execute_qa_plan(async=true)`.

Environment

Tools for managing environment configurations used during execution.

Tool	Description
`create_environment`	Create or overwrite an environment file at `.aqua/environments/<name>.json`.
`list_environments`	List all environment configurations with their notes.
`validate_environment`	Validate an environment file’s schema and check that secrets can be resolved.

Common Scenario

Tools for managing reusable scenario templates that can be copied into QA plans.

Tool	Description
`create_common_scenario`	Create a reusable scenario template.
`get_common_scenario`	Retrieve a common scenario by ID.
`list_common_scenarios`	List all common scenarios in the project.
`update_common_scenario`	Update an existing common scenario.
`delete_common_scenario`	Delete a common scenario. Does not affect plans that have already copied it.

Recording

Tools for capturing browser interactions.

Tool	Description
`record_browser_actions`	Open an interactive browser window to record user actions. Returns the recorded actions as a `BrowserStep[]` array.

Exploration

Tools for interactively investigating your application one action at a time. Unlike run_scenario, exploration sessions keep the browser alive between calls, allowing you to try selectors, inspect responses, and build up state incrementally. See the Interactive Exploration guide for details.

Tool	Description
`start_exploration`	Start an interactive exploration session. The browser is maintained between actions so you can build up state incrementally.
`explore_action`	Execute an action within a session (browser step, HTTP request, or browser assertion) and get immediate feedback.
`end_exploration`	End an exploration session and clean up resources (browser process, memory).
`list_exploration_logs`	List recent exploration session logs for the current project.
`get_exploration_log`	Get the full action log from a specific exploration session. Can be used to replay successful actions.

Memory

Tools for managing persistent project-level knowledge.

Tool	Description
`get_project_memory`	Retrieve the project memory. Returns a starter template if no memory has been saved yet.
`save_project_memory`	Save project memory. Performs a full overwrite of the existing content.

Setup

Tools for checking project readiness.

Tool	Description
`check_project_setup`	One-shot status check that reports on local config, project memory, environments, and common scenarios.