> For the complete documentation index, see [llms.txt](https://docs.aqua-cloud.io/documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.aqua-cloud.io/documentation/integrations/aqua-mcp.md). # 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)](https://aquacloudfiles.blob.core.windows.net/miscellaneous/aqua%20v2.6.0.mcpb?sp=r\&st=2026-09-28T11:02:08Z\&se=2027-12-31T20:17:08Z\&spr=https\&sv=2026-02-06\&sr=b\&sig=y7QR7MMQAHBF4hnkew3evma99cSdtvdcje88y%2BXwoaw%3D) ### 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](https://claude.ai/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 | 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: ``` Which aqua projects do I have access to? ``` ### 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 a**sk the assistant.** Once the MCP server is connected, ask: ``` List my aqua projects with their IDs. ``` 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](https://docs.aqua-cloud.io/documentation/user-administration/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 ``` Read requirement RQ-1042 and create 5 test cases that cover its acceptance criteria. Add test steps to each and link them to the requirement. ``` #### Find coverage gaps ``` List all requirements in status "Approved" that have no linked test case. ``` #### Create a defect from a test result or error log ``` Create a defect for this error, add the log as an attachment and link it to test case TC-318: ``` #### Generate test data ``` Create test data for TC-205 with 10 value sets for valid and invalid IBANs, email addresses and postal codes. ``` #### Status reports and daily overviews ``` Summarize all open defects with priority High, grouped by assignee. ``` #### Bulk updates ``` Move all test cases in the folder "Checkout" that are still in status "Draft" to "Ready for review" and assign them to Anna. ``` #### Review and improve existing items ``` Check test cases TC-100 to TC-120 for missing expected results and suggest improvements. ``` #### User onboarding (administrators) ``` Create a user for max.mueller@company.com, assign him to the project "Mobile App" with the role Tester and give him a named license. ``` ### 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](https://docs.aqua-cloud.io/documentation/web-client/how-to-contact-our-support). --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.aqua-cloud.io/documentation/integrations/aqua-mcp.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.