Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

aqua MCP

Overview

The aqua MCP server connects AI assistants to your aqua instance, so you can search, read, create and update aqua items in plain language.

MCP (Model Context Protocol) is an open standard that lets AI assistants use external tools. The aqua MCP server works with MCP-compatible assistants such as Claude, Cursor or GitHub Copilot in VS Code. Once connected, the assistant can work with requirements, test cases, test scenarios and defects, add comments and attachments, manage relations between items and, for administrators, manage users and licenses.

All actions run with the permissions of the aqua user you connect with. The assistant cannot see or change anything that this user cannot see or change in aqua.

Download

The current version is aqua MCP v2.6.0, delivered as an MCP bundle file (.mcpb). Claude Desktop installs this file directly. For other assistants, follow their instructions for adding a local MCP server.

Download aqua MCP v2.6.0 (.mcpb)

Setup in Claude Desktop

The following steps show the setup in Claude Desktop. Other MCP-compatible assistants work similarly: add the aqua MCP server in the assistant's MCP settings and enter the same connection details.

Prerequisites

  • Claude Desktop installed on Windows or macOS (download)

  • An active aqua user account with API access and access to the projects you want to use

  • The aqua MCP .mcpb file (see Download above)

Install the extension

  1. Download the aqua v2.6.0.mcpb file.

  2. Open Claude Desktop and go to Settings > Extensions.

  3. Drag the .mcpb file into the Extensions window, or double-click the file to open it with Claude Desktop.

  4. Click Install in the dialog that appears.

Connect to your aqua instance

After installation, Claude Desktop asks for the connection details:

Field

What to enter

aqua URL

The address of your aqua instance, e.g. https://yourcompany.aqua-cloud.io

User name

Your aqua user name

Password

Your aqua password

Default project ID (optional)

The project Claude should use unless you name another one. Leave empty to search across all projects.

Click Save, then make sure the extension toggle is set to Enabled.

Note: Your credentials are stored locally by Claude Desktop and are only used to call the aqua API.

Test the connection

Start a new chat and ask:

Find your project ID

Claude should list your projects. You can switch the working project at any time, e.g. "Switch to project Webshop Release 3".

You only need a project ID if you want to set a default project. The ID is a number, e.g. 408.

In aqua. Open the project in the aqua web client. The project ID is the number shown in the URL in your browser's address bar.

Or ask the assistant. Once the MCP server is connected, ask:

The assistant returns every project you have access to, with its ID. Copy the ID of the project you want and enter it in the Default project field.

Tip: In the chat, you can always switch projects by name, e.g. "Switch to project Login Page Project".

Permissions

Two layers control what the assistant can do: your aqua permissions and the tool permissions in your AI assistant.

aqua permissions

The MCP server acts as the aqua user you connected with. The assistant only sees the projects, folders and items this user can access, and can only perform actions allowed by the user's role (see Roles and permissions).

Tool group

Required in aqua

Read and search items, comments, history, attachments

Read access to the project

Create and edit items, test steps, test data, comments, relations

Edit rights for the item type in the project role

Change item status

A workflow transition allowed for the user's role

Delete attachments or comments

Delete rights in the project role

User and license administration

Server administrator

Tip: For everyday testing work, connect with a regular project user rather than an administrator account. The administration tools then return a permission error instead of making changes.

Tool permissions in your AI assistant

Most assistants let you control which tools may run without asking. In Claude Desktop, go to Settings > Extensions > aqua and set each tool to one of these options:

  • Always allow – The assistant runs the tool without asking.

  • Needs approval – The assistant asks you before every call. This is the default.

  • Blocked – The assistant cannot use the tool.

We recommend allowing read tools, keeping approval on for tools that create or change data, and blocking the user administration tools if you don't need them.

Available tools

Version 2.6.0 includes 44 tools. You don't call them directly: the assistant picks the right tool based on your request.

Area

Tools

What the assistant can do

Projects

list-projects, get-current-project, set-current-project, get-statuses-for-project, list-field-ids

List projects, switch the working project, look up statuses and field names

Search and read

global-search, list-items, get-item-details, get-item-history, get-item-relations

Find items by text or filter (status, assignee, priority, sprint) and read full item details. Global search covers all projects when no default project is set.

Create and edit

create-item, update-item-fields, update-item-status, assign-item

Create requirements, test cases, test scenarios and defects (incl. sub-requirements), update fields, move status, assign users

Test cases

get-test-steps, add-test-steps, get-test-data, set-test-data

Read and add test steps, read and replace test data (value sets)

Relations

add-item-relationship

Link items, e.g. a test case to a requirement or a defect to a test case

Comments

get-item-comments, add-comment-to-item, update-comment-on-item, delete-comment-on-item

Read and write discussion comments

Attachments

list-attachments, download-attachment, upload-attachment, delete-attachment

Work with item attachments

Users and licenses (admin)

list-users, get-user, create-user, update-user, activate-user, deactivate-user, reset-user-password, set-user-password, set-server-administrator, list-roles, list-project-users, assign-user-to-project, unassign-user-from-project, list-licenses, list-assigned-licenses, assign-user-license, remove-user-license

Manage users, project assignments, roles and licenses

Embedded images

get-item-details (downloadImages parameter)

Download images from rich-text descriptions so the assistant can view them

Built-in guide

aqua-guide (MCP prompt)

Teaches the assistant how to use the aqua tools effectively

Warning: set-test-data replaces all existing test data of a test case. Value sets that are not included in the request are deleted.

Use cases

The examples below show typical prompts. The assistant combines several tools per request, so you can describe the goal in plain language.

Generate test cases from a requirement

Find coverage gaps

Create a defect from a test result or error log

Generate test data

Status reports and daily overviews

Bulk updates

Review and improve existing items

User onboarding (administrators)

Troubleshooting

Problem

Solution

The assistant doesn't use the aqua tools

Check that the aqua MCP server is enabled in your assistant's settings (in Claude Desktop: Settings > Extensions) and that its tools are turned on for the chat. Restart the assistant after installing.

Login or connection error

Check the aqua URL (no trailing path), user name and password. Accounts that sign in only via SSO may need a separate aqua password.

Items or projects are missing

The connected user has no access to them. Check the user's project assignment and role in aqua.

"Permission denied" when creating or changing items

The user's role doesn't allow this action, or the workflow doesn't allow the status transition.

The assistant works in the wrong project

Ask the assistant to switch the project, or name the project in your prompt.

Still stuck? Contact our support.

PreviousSample
NextDesktop Client

Last updated

Was this helpful?