TestLabIQ
← Alle Hilfe-Artikel

Agent-Zugang (KI-Support & Automatisierung)

Was ist das?

Programme (der KI-Support-Assistent, eigene Automatisierungen, Fremdsysteme) können auf einen begrenzten, klar definierten Satz von Funktionen Ihrer Organisation zugreifen — den „Tool-Layer" — ohne sich als Mensch anzumelden. Derselbe Zugang authentifiziert auch die REST-API (/api/v1/projects, /api/v1/test-cases, …).

Es gibt zwei Wege:

  • Anmeldung per OAuth (für KI-Assistenten wie Claude, ChatGPT, Cursor oder VS Code): Sie tragen nur die Adresse ein, melden sich im Browser an und stimmen zu. Das richten Sie selbst ein, ohne Token — siehe Abschnitt „Anbindung über MCP" unten.
  • Agent-Token (für Automatisierungen ohne Menschen davor, z. B. Skripte oder Server): ein festes Token im Header. Diese Tokens richten wir für Sie ein — eine eigene Oberfläche zum Ausstellen gibt es dafür noch nicht; wenden Sie sich an unser Team.

So funktioniert es

  • Rechte: Jeder programmatische Zugriff läuft über dasselbe Rechtemodell wie ein menschliches Mitglied und sieht ausschliesslich Ihre eigene Organisation. Ein Token bekommt beim Anlegen eine Rolle (VIEWER/MEMBER/ADMIN, Default VIEWER) — sie bestimmt, welche der unten genannten Tools es nutzen darf, genau wie bei einem menschlichen Mitglied dieser Rolle. OWNER ist für Tokens ausgeschlossen: Mitgliederrechte ändern bleibt ausschliesslich menschlichen Personen vorbehalten.
  • Nachvollziehbar: Jede Aktion steht im Audit-Log mit Akteurstyp Agent, bei OAuth zusätzlich mit der Person, in deren Auftrag die App handelt.

Verfügbare Tools

  • search_docs — durchsucht diese Hilfe-Dokumentation.
  • get_org_overview — Kennzahlen (Projekte, Prüfstände, Prüflinge, …).
  • get_calibration_status — fällige/überfällige Gerätekalibrierungen.
  • list_recent_audit_events — jüngste Änderungen (nur mit Admin-Rolle).
  • get_webhook_deliveries — Webhook-Zustellversuche (nur mit Admin-Rolle).
  • get_ingestion_deliveries — Messdaten-Zustellungen (REST/MQTT) mit Erfolg/Fehler je Prüfstand.
  • get_report_status — aktueller Berichtsstatus und gespeicherte Fehlerursache, optional gefiltert nach Bericht oder Projekt.
  • get_capacity_forecast — Kapazitätsprognose je Prüfstandstyp (Auslastung, Spitzenlast, Rückstand, fehlende Prüfstände), optional als Was-wäre-wenn; speichert nichts (siehe Kapazitätsprognose).
  • list_projects, list_test_runs, list_stations, find_test_objects, list_nonconformances, list_equipment, list_customers, list_test_cases, list_station_types, list_test_object_types, list_equipment_types, list_test_run_items, get_custody_trail — lesender Zugriff auf die jeweiligen Fachdaten.

Schreibende Tools (ab Rolle MEMBER)

  • create_station/create_station_type, create_test_object/ create_test_object_type, create_equipment/create_equipment_type, create_customer, create_project, update_project, update_customer, create_test_case, update_test_case, record_custody_event, create_nonconformance, create_test_run, create_test_run_item — legen direkt Daten an bzw. ändern sie. create_test_run legt eine neue Testsequenz in einem Projekt an (braucht einen festen Startzeitpunkt oder mindestens eine Abhängigkeit zu einer anderen Sequenz); create_test_run_item fügt ihr einen Prüfschritt hinzu, wahlweise mit einem Testfall aus der Bibliothek oder einem neu angelegten. Anders als im Chat des KI-Support-Assistenten (dort erst nach Bestätigung durch die Kundschaft) führt ein Programm mit einem eigenen Token diese Aktionen sofort aus, sobald es das Tool aufruft — es gibt hier keine Bestätigungs-Zwischenstufe. Ein solches Token gehört deshalb nur in vertrauenswürdige eigene Automatisierungen, nicht in die Hände Dritter. update_project/update_customer/update_test_case ersetzen bei jedem Aufruf den vollständigen Datensatz — ein weggelassenes optionales Feld wird geleert, nicht unverändert gelassen. Ebenso update_station, update_test_object, update_equipment (das Foto lässt sich darüber nicht ändern).
  • Dazu: update_station_status, set_station_maintenance_window, update_equipment_status (Status/Wartungstermin setzen), update_project_status_mode, create_project_baseline, activate_project_baseline, restore_project_revision, restore_test_run_revision (Terminplanung/Revisionen eines Projekts bzw. einer Testsequenz), create_qualification, grant_qualification, create_absence_for_member, set_station_operators (Personalverwaltung), assign_custody_code (scannbaren Code vergeben) und create_document_folder.
  • Prüfschritte pflegen: set_test_run_item_station, reassign_test_run_items_station, set_test_run_item_dependencies, set_test_run_dependencies, set_test_run_item_start, set_test_run_start, set_test_run_item_progress, add_test_run_item_note, set_test_run_item_assignee, set_test_run_item_equipment, update_test_run_item_due_date, update_test_run_status_mode — Prüfstand-Zuordnung, Terminierung, Abhängigkeiten, Fortschritt, Notizen, Zuständigkeit, Rückverfolgbarkeits- Equipment und Fälligkeit einzelner Prüfschritte bzw. einer ganzen Testsequenz.
  • Meilensteine: create_milestone, update_milestone, set_milestone_reached, set_milestone_date — optional automatisch erreicht, sobald eine bestimmte Testsequenz oder ein bestimmter Prüfschritt besteht.
  • Bewusst nicht dabei: Löschen, Mitgliederrechte ändern, Einstellungen (Webhooks, API-Keys) sowie die eigentliche Testlauf-Ausführung (Prüfergebnis erfassen, Prüfschritt-Status auf bestanden/fehlgeschlagen setzen, strukturierte Messergebnisse bearbeiten, Massenänderungen) — diese Logik hat Webhook-, Benachrichtigungs- und Meilenstein-Seiteneffekte und noch keine automatisierte Testabdeckung; sie wird erst mit eigenen Tests headless gemacht, nicht mechanisch verschoben. Ebenfalls noch nicht angebunden: Dateien/Fotos hochladen.

Anbindung über MCP (Model Context Protocol)

TestLabIQ hat einen eingebauten MCP-Server. MCP ist ein offener Standard — der Server ist an keinen bestimmten KI-Anbieter gebunden. Jeder Client, der den MCP-Transport Streamable HTTP spricht, funktioniert.

Adresse: https://app.testlabiq.com/api/v1/agent/mcp

Empfohlen: Anmeldung per OAuth

Tragen Sie in Ihrem KI-Client nur die Adresse ein. Beim ersten Verbinden öffnet der Client ein Browserfenster:

  1. Sie melden sich wie gewohnt bei TestLabIQ an.
  2. Sie sehen, welche App Zugriff möchte und wohin es danach weitergeht.
  3. Sie wählen die Organisation und was die App darf: Nur lesen, Lesen und bearbeiten oder Verwalten — höchstens Ihre eigene Rolle.
  4. Mit Zulassen ist die App verbunden.

Die App handelt danach in Ihrem Auftrag: im Audit-Log steht jede Aktion als Agent — im Auftrag von Ihnen. Sie kann nie mehr als Sie selbst: wird Ihre Rolle herabgestuft oder verlassen Sie die Organisation, gilt das sofort auch für die App. Unter Einstellungen → Meine Einstellungen → Verbundene Apps sehen Sie alle Verbindungen mit letzter Nutzung und können jede sofort trennen.

So geht es in gängigen Clients:

  • Claude (Web, Desktop, Mobil) und ChatGPT: einen eigenen Konnektor hinzufügen (bei ChatGPT im Entwicklermodus) und als URL die Adresse oben eintragen. Anmeldung: OAuth.

  • Claude Code:

    claude mcp add -s user --transport http testlabiq https://app.testlabiq.com/api/v1/agent/mcp

    danach in einer Sitzung /mcp aufrufen und „Authenticate" wählen.

  • Cursor (~/.cursor/mcp.json):

    { "mcpServers": { "testlabiq": { "url": "https://app.testlabiq.com/api/v1/agent/mcp" } } }

  • VS Code / GitHub Copilot (.vscode/mcp.json oder „MCP: Open User Configuration"):

    { "servers": { "testlabiq": { "type": "http", "url": "https://app.testlabiq.com/api/v1/agent/mcp" } } }

  • Andere Clients: Adresse eintragen; unterstützt der Client OAuth für MCP-Server, startet die Anmeldung von selbst. Er findet unseren Anmeldeserver automatisch (Metadaten nach RFC 9728/8414) und registriert sich selbst (Dynamic Client Registration) — Sie müssen nichts weiter konfigurieren.

Der Name, unter dem Sie den Server im Client eintragen (oben testlabiq), ist frei wählbar. Für mehrere Organisationen verbinden Sie die App einfach mehrfach — je Verbindung wählen Sie eine Organisation.

Alternativ: Agent-Token im Header

Für Automatisierungen ohne Menschen davor (Skripte, Server, CI) gibt es das feste Agent-Token. Es geht im Header x-agent-token mit (alternativ Authorization: Bearer <token>); eine Anmeldung im Browser entfällt.

Claude Code:

claude mcp add -s user --transport http testlabiq \
  https://app.testlabiq.com/api/v1/agent/mcp \
  -H 'x-agent-token: ${TESTLABIQ_TOKEN}'

Die einfachen Anführungszeichen sind wichtig: so landet der Platzhalter in der Konfiguration und wird bei jedem Verbindungsaufbau frisch aus der Umgebung aufgelöst — mit doppelten Anführungszeichen expandiert die eigene Shell sofort und der Klartext steht doch in der Datei.

Cursor: wie oben, zusätzlich "headers": { "x-agent-token": "${env:TESTLABIQ_TOKEN}" }.

VS Code: wie oben, zusätzlich "headers": { "x-agent-token": "${input:testlabiq-token}" } und ein passender Eintrag unter "inputs" ("type": "promptString", "password": true) — VS Code fragt das Token dann einmal ab und speichert es verschlüsselt.

Codex CLI (~/.codex/config.toml):

[mcp_servers.testlabiq]
url = "https://app.testlabiq.com/api/v1/agent/mcp"
bearer_token_env_var = "TESTLABIQ_TOKEN"

Eigene Agenten mit dem offiziellen MCP-SDK (TypeScript):

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const client = new Client({ name: "mein-agent", version: "1.0.0" });
await client.connect(
  new StreamableHTTPClientTransport(new URL("https://app.testlabiq.com/api/v1/agent/mcp"), {
    requestInit: { headers: { "x-agent-token": process.env.TESTLABIQ_TOKEN! } },
  }),
);
const { tools } = await client.listTools();

In Python entsprechend streamablehttp_client(url, headers={"x-agent-token": token}).

Verbindung ohne Client testen (Agent-Token)

curl -s https://app.testlabiq.com/api/v1/agent/mcp \
  -H "x-agent-token: $TESTLABIQ_TOKEN" \
  -H "content-type: application/json" \
  -H "accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Kommt eine Liste von Tools zurück, ist der Zugang in Ordnung und ein verbleibendes Problem liegt in der Client-Konfiguration. Ein 401 heisst: Token fehlt, ist falsch oder gesperrt.

Welche Organisation gilt?

Das ist nicht pro Aufruf wählbar, und zwar mit Absicht: kein einziges Tool nimmt eine Organisation als Parameter entgegen. Die Organisation kommt ausschliesslich aus dem Zugang selbst — so kann auch eine manipulierte Anweisung an die KI sie nicht umbiegen.

  • Bei OAuth wählen Sie die Organisation beim Zustimmen; sie gilt für genau diese Verbindung.
  • Ihr eigenes Agent-Token ist beim Ausstellen fest an genau eine Organisation gebunden. Wer mehrere Organisationen bedienen möchte, lässt sich je Organisation ein Token ausstellen und richtet je Token einen eigenen MCP-Zugang ein (z. B. testlabiq-labor-nord, testlabiq-labor-sued).
  • Beim Betreiber-Zugang (ein einziges Token über alle Organisationen hinweg) gehört die Ziel-Organisation in den zusätzlichen Header x-agent-org — als Organisations-Slug oder -ID. Fehlt der Header, wird bewusst gar nichts aufgelöst, damit ein vergessener Header nicht in einer zufälligen Organisation landet.

Typische Probleme

  • „Ich finde keine Seite, um ein Token anzulegen oder zu sperren." Für KI-Assistenten brauchen Sie keins — verbinden Sie per OAuth (siehe oben), getrennt wird unter Verbundene Apps. Feste Agent-Tokens für Automatisierungen richten wir ein; wenden Sie sich dafür oder bei Auffälligkeiten an unser Team.
  • „Der Client meldet ‚needs authentication' / bietet eine Anmeldung an." Das ist bei OAuth der normale erste Schritt — Anmeldung starten. Haben Sie ein Agent-Token eingetragen, ist es fehlend oder ungültig (oft: die Umgebungsvariable ist in der Umgebung, aus der der Client startet, nicht gesetzt; viele Clients lesen keine .env-Datei).
  • „Auf der Zustimmungsseite ist meine Organisation ausgegraut." Der Agent-Zugang ist für diese Organisation abgeschaltet (Not-Aus). Wenden Sie sich an eine Administratorin bzw. einen Administrator.
  • „Ich kann nur ‚Nur lesen' wählen." Eine App bekommt höchstens Ihre eigene Rolle.
  • „Die App war verbunden und ist plötzlich wieder abgemeldet." Mögliche Gründe: Sie (oder die App selbst) haben die Verbindung getrennt; Sie sind nicht mehr Mitglied der Organisation; oder die App hat ein bereits verbrauchtes Erneuerungs-Token ein zweites Mal geschickt — das werten wir als möglichen Diebstahl und trennen die Verbindung vorsorglich. Der Grund steht im Audit-Log („KI-App getrennt"). Einfach erneut verbinden.
  • „Die App darf etwas nicht, das ich selbst darf." Prüfen Sie unter Verbundene Apps, welche Rolle Sie beim Zustimmen gewählt haben; für mehr Rechte trennen und mit höherer Rolle neu verbinden.
  • „401 / Ungültiges Token." Das eingerichtete Token ist falsch oder gesperrt — bzw. bei OAuth: die Verbindung wurde getrennt oder der Agent-Zugang der Organisation abgeschaltet.
  • „403 / Keine Berechtigung." Der eingerichtete Zugang darf dieses Tool nicht nutzen. Die Diagnose-Tools zu Audit und Webhooks setzen Admin-Rechte voraus.
  • „Der Agent sieht Daten einer anderen Organisation." Kann nicht passieren: jeder Zugriff ist an genau eine Organisation gebunden, die Mandantentrennung gilt auch hier auf Datenbankebene.

Noch Fragen?

Wir zeigen Ihnen TestLabIQ gern live – mit Ihren eigenen Anwendungsfällen.

Demo anfragen