> 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/de-documentation/integration/aqua-mcp.md). # aqua MCP ### Überblick Der aqua MCP-Server verbindet KI-Assistenten mit Ihrer aqua-Instanz. So können Sie aqua-Elemente in natürlicher Sprache suchen, lesen, erstellen und bearbeiten. MCP (Model Context Protocol) ist ein offener Standard, über den KI-Assistenten externe Tools nutzen können. Der aqua MCP-Server funktioniert mit MCP-kompatiblen Assistenten wie Claude, Cursor oder GitHub Copilot in VS Code. Nach der Verbindung kann der Assistent mit Anforderungen, Testfällen, Testszenarien und Defekten arbeiten, Kommentare und Anhänge hinzufügen, Beziehungen zwischen Elementen verwalten und – für Administratoren – Benutzer und Lizenzen verwalten. Alle Aktionen laufen mit den Berechtigungen des aqua-Benutzers, mit dem Sie sich verbinden. Der Assistent kann nichts sehen oder ändern, was dieser Benutzer in aqua nicht sehen oder ändern kann. ### Download Die aktuelle Version ist **aqua MCP v2.6.0** und wird als MCP-Bundle-Datei (`.mcpb`) bereitgestellt. Claude Desktop installiert diese Datei direkt. Für andere Assistenten folgen Sie deren Anleitung zum Hinzufügen eines lokalen MCP-Servers. [aqua MCP v2.6.0 herunterladen (.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) ### Einrichtung in Claude Desktop Die folgenden Schritte zeigen die Einrichtung in Claude Desktop. Andere MCP-kompatible Assistenten funktionieren ähnlich: Fügen Sie den aqua MCP-Server in den MCP-Einstellungen des Assistenten hinzu und geben Sie dieselben Verbindungsdaten ein. #### Voraussetzungen * Claude Desktop, installiert unter Windows oder macOS ([Download](https://claude.ai/download)) * Ein aktives aqua-Benutzerkonto mit API-Zugriff und Zugriff auf die gewünschten Projekte * Die aqua MCP-Datei `.mcpb` (siehe Download oben) #### Erweiterung installieren 1. Laden Sie die Datei `aqua v2.6.0.mcpb` herunter. 2. Öffnen Sie Claude Desktop und gehen Sie zu **Einstellungen > Erweiterungen**. 3. Ziehen Sie die `.mcpb`-Datei in das Fenster „Erweiterungen“ oder öffnen Sie die Datei per Doppelklick mit Claude Desktop. 4. Klicken Sie im angezeigten Dialog auf **Installieren**. #### Mit Ihrer aqua-Instanz verbinden Nach der Installation fragt Claude Desktop nach den Verbindungsdaten: | Feld | Eingabe | | ------------------ | ---------------------------------------------------------------------------------------------------------------------- | | aqua-URL | Die Adresse Ihrer aqua-Instanz, z. B. `https://ihrefirma.aqua-cloud.io` | | Benutzername | Ihr aqua-Benutzername | | Passwort | Ihr aqua-Passwort | | Standardprojekt ID | Das Projekt, das der Assistent verwendet, wenn Sie kein anderes nennen. Leer lassen, um projektübergreifend zu suchen. | Klicken Sie auf **Speichern** und stellen Sie sicher, dass die Erweiterung **aktiviert** ist. > **Hinweis:** Ihre Zugangsdaten werden lokal von Claude Desktop gespeichert und nur für Aufrufe der aqua-API verwendet. #### Verbindung testen Starten Sie einen neuen Chat und fragen Sie: ``` Auf welche aqua-Projekte habe ich Zugriff? ``` Der Assistent sollte Ihre Projekte auflisten. Sie können das Arbeitsprojekt jederzeit wechseln, z. B. *„Wechsle zum Projekt Webshop Release 3“*. ### Projekt-ID finden Eine Projekt-ID benötigen Sie nur, wenn Sie ein Standardprojekt festlegen möchten. Die ID ist eine Zahl, z. B. `408`. **In aqua.** Öffnen Sie das Projekt im aqua Web-Client. Die Projekt-ID ist die Zahl in der URL in der Adresszeile Ihres Browsers. **Oder fragen Sie den Assistenten.** Sobald der MCP-Server verbunden ist, fragen Sie: ``` Liste meine aqua-Projekte mit ihren IDs auf. ``` Der Assistent gibt alle Projekte, auf die Sie Zugriff haben, mit ihrer ID zurück. Kopieren Sie die ID des gewünschten Projekts und tragen Sie sie im Feld **Standardprojekt** ein. > **Tipp:** Im Chat können Sie jederzeit per Projektname wechseln, z. B. *„Wechsle zum Projekt Login Page Project“*. ### Berechtigungen Zwei Ebenen steuern, was der Assistent tun kann: Ihre aqua-Berechtigungen und die Tool-Berechtigungen in Ihrem KI-Assistenten. #### aqua-Berechtigungen Der MCP-Server handelt als der aqua-Benutzer, mit dem Sie sich verbunden haben. Der Assistent sieht nur die Projekte, Ordner und Elemente, auf die dieser Benutzer Zugriff hat, und kann nur Aktionen ausführen, die die Rolle des Benutzers erlaubt (siehe [Rollen und Berechtigungen](https://docs.aqua-cloud.io/documentation/user-administration/roles-and-permissions)). | Tool-Gruppe | Erforderlich in aqua | | -------------------------------------------------------------------------------------- | --------------------------------------------------------- | | Elemente, Kommentare, Historie und Anhänge lesen und durchsuchen | Lesezugriff auf das Projekt | | Elemente, Testschritte, Testdaten, Kommentare und Beziehungen erstellen und bearbeiten | Bearbeitungsrechte für den Elementtyp in der Projektrolle | | Status eines Elements ändern | Ein für die Rolle erlaubter Workflow-Übergang | | Anhänge oder Kommentare löschen | Löschrechte in der Projektrolle | | Benutzer- und Lizenzverwaltung | Serveradministrator | > **Tipp:** Verbinden Sie sich für die tägliche Testarbeit mit einem normalen Projektbenutzer statt mit einem Administratorkonto. Die Verwaltungstools geben dann eine Berechtigungsfehlermeldung zurück, statt Änderungen vorzunehmen. #### Tool-Berechtigungen in Ihrem KI-Assistenten In den meisten Assistenten können Sie festlegen, welche Tools ohne Rückfrage ausgeführt werden dürfen. Gehen Sie in Claude Desktop zu **Einstellungen > Erweiterungen > aqua** und wählen Sie für jedes Tool eine dieser Optionen: * **Immer erlauben** – Der Assistent führt das Tool ohne Rückfrage aus. * **Genehmigung erforderlich** – Der Assistent fragt vor jedem Aufruf nach. Dies ist die Standardeinstellung. * **Blockiert** – Der Assistent kann das Tool nicht verwenden. Wir empfehlen, Lese-Tools zu erlauben, die Genehmigung für Tools, die Daten erstellen oder ändern, beizubehalten und die Benutzerverwaltungstools zu blockieren, wenn Sie sie nicht benötigen. ### Verfügbare Tools Version 2.6.0 enthält 44 Tools. Sie rufen sie nicht direkt auf: Der Assistent wählt anhand Ihrer Anfrage das passende Tool. | Bereich | Tools | Was der Assistent tun kann | | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Projekte | list-projects, get-current-project, set-current-project, get-statuses-for-project, list-field-ids | Projekte auflisten, Arbeitsprojekt wechseln, Status und Feldnamen abfragen | | Suchen und lesen | global-search, list-items, get-item-details, get-item-history, get-item-relations | Elemente per Text oder Filter (Status, Zuständiger, Priorität, Sprint) finden und alle Details lesen. Die globale Suche durchsucht alle Projekte, wenn kein Standardprojekt festgelegt ist. | | Erstellen und bearbeiten | create-item, update-item-fields, update-item-status, assign-item | Anforderungen, Testfälle, Testszenarien und Defekte (inkl. Unteranforderungen) erstellen, Felder aktualisieren, Status ändern, Benutzer zuweisen | | Testfälle | get-test-steps, add-test-steps, get-test-data, set-test-data | Testschritte lesen und hinzufügen, Testdaten (Wertesätze) lesen und ersetzen | | Beziehungen | add-item-relationship | Elemente verknüpfen, z. B. einen Testfall mit einer Anforderung oder einen Defekt mit einem Testfall | | Kommentare | get-item-comments, add-comment-to-item, update-comment-on-item, delete-comment-on-item | Diskussionskommentare lesen und schreiben | | Anhänge | list-attachments, download-attachment, upload-attachment, delete-attachment | Mit Anhängen von Elementen arbeiten | | Benutzer und Lizenzen (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 | Benutzer, Projektzuweisungen, Rollen und Lizenzen verwalten | | Eingebettete Bilder | get-item-details (Parameter downloadImages) | Bilder aus Rich-Text-Beschreibungen herunterladen, damit der Assistent sie ansehen kann | | Integrierte Anleitung | aqua-guide (MCP-Prompt) | Zeigt dem Assistenten, wie er die aqua-Tools effektiv nutzt | > **Warnung:** `set-test-data` ersetzt alle vorhandenen Testdaten eines Testfalls. Wertesätze, die nicht in der Anfrage enthalten sind, werden gelöscht. ### Anwendungsfälle Die folgenden Beispiele zeigen typische Prompts. Der Assistent kombiniert mehrere Tools pro Anfrage, Sie können Ihr Ziel also in natürlicher Sprache beschreiben. #### Testfälle aus einer Anforderung generieren ``` Lies die Anforderung RQ-1042 und erstelle 5 Testfälle, die ihre Akzeptanzkriterien abdecken. Füge jedem Testfall Testschritte hinzu und verknüpfe sie mit der Anforderung. ``` #### Abdeckungslücken finden ``` Liste alle Anforderungen im Status "Freigegeben" auf, die keinen verknüpften Testfall haben. ``` #### Defekt aus einem Testergebnis oder Fehlerlog erstellen ``` Erstelle einen Defekt für diesen Fehler, hänge das Log als Anhang an und verknüpfe ihn mit dem Testfall TC-318: ``` #### Testdaten generieren ``` Erstelle Testdaten für TC-205 mit 10 Wertesätzen für gültige und ungültige IBANs, E-Mail-Adressen und Postleitzahlen. ``` #### Statusberichte und tägliche Übersichten ``` Fasse alle offenen Defekte mit Priorität Hoch zusammen, gruppiert nach Zuständigem. ``` #### Massenänderungen ``` Setze alle Testfälle im Ordner "Checkout", die noch im Status "Entwurf" sind, auf "Bereit zur Prüfvfung" und weise sie Anna zu. ``` #### Bestehende Elemente prüfen und verbessern ``` Prüfe die Testfälle TC-100 bis TC-120 auf fehlende erwartete Ergebnisse und schlage Verbesserungen vor. ``` #### Benutzer-Onboarding (Administratoren) ``` Lege einen Benutzer für max.mueller@company.com an, weise ihn dem Projekt "Mobile App" mit der Rolle Tester zu und gib ihm eine Named-Lizenz. ``` ### Fehlerbehebung | Problem | Lösung | | ------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Der Assistent nutzt die aqua-Tools nicht | Prüfen Sie, ob der aqua MCP-Server in den Einstellungen Ihres Assistenten aktiviert ist (in Claude Desktop: **Einstellungen > Erweiterungen**) und ob seine Tools für den Chat eingeschaltet sind. Starten Sie den Assistenten nach der Installation neu. | | Anmelde- oder Verbindungsfehler | Prüfen Sie die aqua-URL (ohne angehängten Pfad), den Benutzernamen und das Passwort. Konten, die sich nur per SSO anmelden, benötigen eventuell ein separates aqua-Passwort. | | Elemente oder Projekte fehlen | Der verbundene Benutzer hat keinen Zugriff darauf. Prüfen Sie die Projektzuweisung und Rolle des Benutzers in aqua. | | „Keine Berechtigung“ beim Erstellen oder Ändern von Elementen | Die Rolle des Benutzers erlaubt diese Aktion nicht, oder der Workflow erlaubt den Statusübergang nicht. | | Der Assistent arbeitet im falschen Projekt | Bitten Sie den Assistenten, das Projekt zu wechseln, oder nennen Sie das Projekt in Ihrem Prompt. | Kommen Sie nicht weiter? [Kontaktieren Sie unseren 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/de-documentation/integration/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.