Tool reference

Die MCP-(Model Context Protocol)-Services stellen rund 208 Tools bereit (MCP Services 3.4, Oktober 2026), gruppiert in die unten aufgeführten Familien. Die meisten Platform-Admin-Tools spiegeln den entsprechenden octo-cli-Befehl (snake_case-Namen – z. B. CLI CreateTenant → MCP create_tenant); die Aggregations- und Persisted-Query-Tools spiegeln die GraphQL-Transient-Query-Oberfläche des Asset Repository.

Notation in dieser Referenz:

• ^‡ — destruktiv, erfordert confirm: true
• ^📁 — verwendet die File-Transfer-Endpunkte
• Alle tenant-bezogenen Tools akzeptieren einen optionalen tenantId-Parameter (fällt auf die URL-Route zurück)

Sie können den Live-Katalog jederzeit von einem verbundenen Client aus entdecken:

{ "tool": "list_available_tools" }
{ "tool": "get_tool_details",  "parameters": { "name": "create_tenant" } }

Authentifizierung & Identity-Bootstrap (6)

Tool	Zweck
authenticate	Startet den OAuth2 Device Authorization Flow – gibt Verifizierungs-URL und User-Code zurück
check_auth_status	Prüft, ob die Browser-Anmeldung abgeschlossen ist
auth_status	Zeigt den Authentifizierungsstatus an; aktualisiert optional ein abgelaufenes Access-Token
whoami	Gibt den authentifizierten Benutzer zurück (Name, E-Mail, Rollen, Tenants)
list_tenants	Listet jeden Tenant auf, auf den der authentifizierte Benutzer Zugriff hat
switch_tenant	Wechselt den operierenden Tenant der Sitzung ohne erneute Anmeldung (RFC 8693 Token Exchange; Rollen werden im Ziel-Tenant neu aufgelöst; fällt auf den Device Flow zurück, wenn kein tenant-übergreifender Zugriff bereitgestellt ist)

Tenant-Lifecycle (11)

Tool	Zweck
get_tenants	Listet die vom Parent-Tenant aus sichtbaren Child-Tenants auf
create_tenant	Erstellt einen neuen Child-Tenant unter dem Parent
delete_tenant‡	Löscht einen Child-Tenant
clean_tenant‡	Setzt einen Child-Tenant auf die Werkseinstellungen zurück
attach_tenant	Hängt eine bestehende Datenbank als Child-Tenant an, ohne neue Daten zu erzeugen
detach_tenant	Trennt einen Child-Tenant ab und bewahrt seine Datenbank
clear_tenant_cache‡	Leert die In-Memory-Caches eines Child-Tenants
update_system_ck_model	Aktualisiert das System-Construction-Kit-Modell eines Child-Tenants auf die aktuelle Version
dump_tenant📁	Erstellt einen Dump der Tenant-Daten und veröffentlicht ihn als herunterladbares .tar.gz
restore_tenant‡📁	Stellt einen Tenant aus einer hochgeladenen Dump-Datei wieder her
get_tenant_features	Liest den Aktivierungszustand von Stream Data, Communication, Reporting und AI Services eines Tenants

Identity — Benutzer (7)

Tool	Zweck
get_users	Listet Benutzer im Tenant auf
create_user	Erstellt ein neues Benutzerkonto, optional mit einem initialen Passwort
update_user	Aktualisiert die E-Mail und/oder den Benutzernamen eines bestehenden Benutzers
delete_user‡	Löscht ein Benutzerkonto
reset_user_password‡	Setzt das Passwort eines Benutzers zurück
add_user_to_role	Weist einem Benutzer eine Rolle zu
remove_user_from_role‡	Entfernt eine Rolle von einem Benutzer

Identity — Rollen (4)

Tool	Zweck
get_roles	Listet Rollen im Tenant auf
create_role	Erstellt eine neue Rolle
update_role	Benennt eine bestehende Rolle um
delete_role‡	Löscht eine Rolle

Identity — Gruppen (10)

Tool	Zweck
get_groups	Listet Gruppen im Tenant auf
get_group	Ruft eine einzelne Gruppe über die Runtime-ID ab
create_group	Erstellt eine neue Gruppe, optional mit Beschreibung und Rollenzuweisungen
update_group	Aktualisiert Gruppen-Metadaten (Name, Beschreibung)
delete_group‡	Löscht eine Gruppe
update_group_roles	Ersetzt alle Rollenzuweisungen einer Gruppe
add_user_to_group	Fügt einen Benutzer zu einer Gruppe hinzu
remove_user_from_group‡	Entfernt einen Benutzer aus einer Gruppe
add_group_to_group	Verschachtelt eine Child-Gruppe innerhalb einer Parent-Gruppe
remove_group_from_group‡	Hebt die Verschachtelung einer Child-Gruppe aus ihrem Parent auf

Identity — OAuth-Clients (20)

Tool	Zweck
get_clients	Listet OAuth-Clients im Tenant auf
get_client	Ruft einen einzelnen OAuth-Client über die Client-ID ab
add_client_credentials_client	Erstellt einen OAuth-Client mit Grant-Typ client_credentials
add_device_code_client	Erstellt einen OAuth-Client mit Grant-Typ device_code
add_authorization_code_client	Erstellt einen OAuth-Client mit Grant-Typ authorization_code
delete_client‡	Löscht einen OAuth-Client
add_scope_to_client	Gewährt einem Client einen Scope durch Anhängen an dessen AllowedScopes
get_client_roles	Listet die direkt einem Client zugewiesenen Rollen-IDs auf
add_client_to_role	Weist einem Client eine Rolle (per Name) zu
remove_client_from_role‡	Entfernt eine Rolle (per Name) von einem Client
update_client_roles	Ersetzt die direkt zugewiesenen Rollen eines Clients (Replace-All)
add_client_to_group	Fügt einen Client (per Runtime-ID) als Gruppenmitglied hinzu
remove_client_from_group‡	Entfernt einen Client aus einer Gruppe
get_client_mirrors	Listet die Child-Tenants auf, in die der markierte ClientCredentials-Client gespiegelt wurde
provision_client_in_existing_tenants	Füllt einen markierten Client in jeden bestehenden Sub-Tenant nach
provision_client_in_tenant	Provisioniert einen Client in einen einzelnen benannten Sub-Tenant
unprovision_client_from_tenant‡	Entfernt eine Client-Spiegelung aus einem Sub-Tenant
set_client_auto_provision	Schaltet das Flag AutoProvisionInChildTenants an einem bestehenden Client um
apply_client_overlay	Hängt betreiberspezifische Overlay-URIs an einen Blueprint-verwalteten OAuth-Client an (überleben ein erneutes Blueprint-Apply)
clean_client_overlays‡	Entfernt Overlay-URI-Einträge aus den Blueprint-verwalteten Clients des Tenants

Identity — Identity Provider (8)

Tool	Zweck
get_identity_providers	Listet Identity Provider im Tenant auf (clientSecret ist immer null — das Tool verwirft auch einen, den ein älterer Identity Service liefern könnte; stattdessen clientSecretIsSet)
update_identity_provider	Aktualisiert gemeinsame Felder an einem bestehenden Identity Provider. Das Client Secret ist nur schreibbar: clientSecret weglassen, um es zu behalten, einen neuen Wert angeben, um es zu rotieren
delete_identity_provider‡	Löscht einen Identity Provider
add_oauth_identity_provider	Erstellt einen Google-, Microsoft- oder Facebook-OAuth-Identity-Provider
add_azure_entra_id_identity_provider	Erstellt einen Azure-Entra-ID-Identity-Provider
add_open_ldap_identity_provider	Erstellt einen OpenLDAP-Identity-Provider
add_active_directory_identity_provider	Erstellt einen Microsoft-Active-Directory-Identity-Provider
add_octo_tenant_identity_provider	Erstellt einen OctoTenant-Identity-Provider für tenant-übergreifende Authentifizierung

Identity — API-Ressourcen, Scopes, Secrets (16)

Tool	Zweck
get_api_resources	Listet OAuth-API-Ressourcen im Tenant auf
create_api_resource	Erstellt eine neue OAuth-API-Ressource
update_api_resource	Aktualisiert eine bestehende OAuth-API-Ressource
delete_api_resource‡	Löscht eine OAuth-API-Ressource
get_api_scopes	Listet OAuth-API-Scopes im Tenant auf
create_api_scope	Erstellt einen neuen OAuth-API-Scope
update_api_scope	Aktualisiert einen bestehenden OAuth-API-Scope
delete_api_scope‡	Löscht einen OAuth-API-Scope
get_client_secrets	Listet an einen Client angehängte API-Secrets auf
create_client_secret	Erstellt ein neues API-Secret an einem Client
update_client_secret	Aktualisiert ein Client-Secret
delete_client_secret‡	Löscht ein Client-Secret
get_api_resource_secrets	Listet an eine API-Ressource angehängte API-Secrets auf
create_api_resource_secret	Erstellt ein neues API-Secret an einer API-Ressource
update_api_resource_secret	Aktualisiert ein API-Ressourcen-Secret
delete_api_resource_secret‡	Löscht ein API-Ressourcen-Secret

Identity — Tenant-übergreifende Zuordnungen & Admin-Provisionierung (14)

Tool	Zweck
get_email_domain_group_rules	Listet E-Mail-Domänen-Gruppenregeln auf
get_email_domain_group_rule	Ruft eine einzelne E-Mail-Domänen-Gruppenregel über die Runtime-ID ab
create_email_domain_group_rule	Erstellt eine Regel, die passende Benutzer automatisch zu einer Gruppe hinzufügt
update_email_domain_group_rule	Aktualisiert eine E-Mail-Domänen-Gruppenregel
delete_email_domain_group_rule‡	Löscht eine E-Mail-Domänen-Gruppenregel
get_external_tenant_user_mappings	Listet externe Tenant-Benutzerzuordnungen auf, mit optionalem Filter
get_external_tenant_user_mapping	Ruft eine einzelne externe Tenant-Benutzerzuordnung über die Runtime-ID ab
create_external_tenant_user_mapping	Erstellt eine neue externe Tenant-Benutzerzuordnung
update_external_tenant_user_mapping	Aktualisiert Rollenzuweisungen an einer externen Tenant-Benutzerzuordnung
delete_external_tenant_user_mapping‡	Löscht eine externe Tenant-Benutzerzuordnung
get_admin_provisioning_mappings	Listet Admin-Provisionierungszuordnungen für den Ziel-Tenant auf
create_admin_provisioning_mapping	Erstellt eine neue Admin-Provisionierungszuordnung
provision_current_user_as_admin	Provisioniert den aufrufenden Benutzer über eine Zuordnung als Admin im Ziel-Tenant
delete_admin_provisioning_mapping‡	Löscht eine Admin-Provisionierungszuordnung

Asset Repository — Blueprints (8)

Tool	Zweck
list_blueprints	Listet über die konfigurierten Kataloge verfügbare Blueprints auf (paginiert)
install_blueprint	Wendet ein Blueprint erstmals auf einen Tenant an, mit optionalem Force-Re-Apply
get_blueprint_history	Gibt die Blueprint-Anwendungshistorie eines Tenants in chronologischer Reihenfolge zurück
get_blueprint_update_info	Gibt Update-Informationen für das aktuelle Blueprint des Tenants zurück
preview_blueprint_update	Zeigt eine Vorschau der Änderungen an, die ein Blueprint-Update anwenden würde, ohne sie anzuwenden
update_blueprint‡	Wendet ein Blueprint-Update an (destruktiv, sofern nicht dryRun=true)
list_blueprint_installations	Listet die aktuell auf einem Tenant installierten Blueprints auf
uninstall_blueprint‡	Entfernt ein Blueprint von einem Tenant

Asset Repository — CK-Modell-Bibliotheken (8)

Tool	Zweck
list_ck_catalogs	Listet die für den Asset-Dienst konfigurierten CK-Modell-Katalogquellen auf
list_ck_catalog_models	Listet in Katalogen verfügbare Modelle auf, mit optionalem Filter
refresh_ck_catalogs	Aktualisiert die CK-Modell-Katalog-Caches
get_ck_library_status	Ruft den zusammengeführten Bibliotheksstatus eines Tenants mit Update-Flags ab
check_ck_dependencies	Löst Abhängigkeiten für ein Katalogmodell auf
check_ck_upgrade	Pre-Flight-Prüfung für das Upgrade/Migrieren eines installierten CK-Modells
import_ck_from_catalog	Importiert ein CK-Modell aus dem Katalog, einschließlich aller Abhängigkeiten
fix_all_ck_models‡	Findet jedes installierte CK-Modell, das ein Update/eine Reparatur benötigt, und reiht Importe in die Warteschlange ein

Service-managed CK models

import_ck_from_catalog ist für dienstverwaltete Modelle (System.*, z. B. System.Communication, System.StreamData, System.Reporting) stillschweigend ein No-Op. Verwenden Sie stattdessen das passende enable_<feature>-Tool – siehe Troubleshooting.

Communication Controller (28)

Lifecycle (2)

Tool	Zweck
enable_communication	Aktiviert den Communication Controller für den Tenant
disable_communication‡	Deaktiviert den Communication Controller; wird mit einem Conflict-Fehler abgelehnt, solange noch Deployment Sites oder Workloads des Tenants bereitgestellt sind – führen Sie zuerst undeploy_workload / undeploy_deployment_site aus

Precondition chain

Machen Sie jedes Workload (undeploy_workload) und jeden Deployment Site (undeploy_deployment_site) rückgängig → disable_communication → delete_tenant / detach_tenant. Jeder Schritt verweigert mit einem Conflict-Fehler und benennt, was noch im Weg steht; Pipelines und Trigger benötigen keinen separaten Schritt.

Adapter (4)

Tool	Zweck
get_adapters	Listet die für den Tenant konfigurierten Adapter auf
get_adapter	Ruft die vollständige Konfiguration eines einzelnen Adapters ab
get_adapter_nodes	Gibt aggregierte Pipeline-Node-Deskriptoren aller verbundenen Adapter zurück
get_pipeline_schema	Gibt das zusammengesetzte Pipeline-JSON-Schema für einen gegebenen Adapter zurück

Pipelines (10)

Tool	Zweck
get_pipeline_status	Ruft den Deployment-Status einer Pipeline ab
deploy_pipeline	Stellt eine Pipeline-Definition (YAML- oder JSON-String) auf einem Adapter bereit
validate_pipeline_definition	Validiert eine Pipeline-Definition gegen das zusammengesetzte Schema des Adapters
execute_pipeline	Führt eine Pipeline aus und gibt die Execution-ID zurück
dry_run_pipeline	Führt eine Pipeline im Dry-Run-Modus aus und unterdrückt die Seiteneffekte von Load-Nodes
set_pipeline_debug	Aktiviert oder deaktiviert die Debug-Erfassung für eine Pipeline
get_pipeline_debug	Ruft den persistierten Debug-Status einer Pipeline ab
get_pipeline_executions	Gibt die Ausführungshistorie der Pipeline zurück
get_latest_pipeline_execution	Gibt die jüngste Pipeline-Ausführung zurück
get_pipeline_debug_points	Gibt Debug-Punkt-Nodes für eine bestimmte Pipeline-Ausführung zurück

Data Flows, Trigger, Deployment Sites (7)

Tool	Zweck
deploy_data_flow	Stellt einen Data Flow bereit
undeploy_data_flow‡	Macht einen Data Flow rückgängig
get_data_flow_status	Ruft den aggregierten Ausführungsstatus eines Data Flow ab
deploy_triggers	Stellt alle Pipeline-Trigger für den Tenant bereit
undeploy_triggers‡	Macht alle Pipeline-Trigger rückgängig
get_deployment_sites	Listet die für den Tenant konfigurierten Pools auf
undeploy_deployment_site‡	Macht einen Pool über den Communication Operator rückgängig (machen Sie zuerst seine Workloads rückgängig)

Workloads & CI/CD-Rollout (5)

Tool	Zweck
get_workloads_by_chart	Listet Workloads im Tenant auf, deren ChartName mit dem angegebenen Namen übereinstimmt
update_workload_chart_version	Setzt die ChartVersion an einem Workload, ohne einen Deploy auszulösen
deploy_workload	Löst einen Deploy eines Workloads über dessen Parent-Deployment-Site aus
undeploy_workload‡	Löst ein Undeploy eines Workloads aus
move_pipelines‡	Weist Pipelines massenhaft vom aktuellen Adapter auf ein neues Ziel neu zu

Zeitreihen, Reporting, Diagnostik (14)

Streamdaten & Archive (13)

Tool	Zweck
enable_stream_data	Aktiviert die Streamdaten-Ingestion für den Tenant
disable_stream_data‡	Deaktiviert Streamdaten; wird abgelehnt, solange noch Archive aktiviert sind, Modell und Daten bleiben erhalten – Voraussetzung für delete_tenant / detach_tenant
activate_archive	Aktiviert ein CkArchive, indem seine archivspezifische CrateDB-Tabelle bereitgestellt wird
disable_archive	Deaktiviert ein CkArchive (Daten bleiben erhalten, Übergang zu Disabled)
enable_archive	Reaktiviert ein zuvor deaktiviertes Archiv
retry_archive_activation	Wiederholt die Archivaktivierung nach einem DDL-Fehler
delete_archive‡	Verwirft die archivspezifische CrateDB-Tabelle
list_rollups_for_archive	Listet jedes an ein Quell-CkArchive angehängte Rollup-Archiv auf
freeze_rollup_archive	Friert ein Rollup-Archiv zu einem gegebenen Zeitstempel ein
unfreeze_rollup_archive	Leert FrozenUntil an einem Rollup-Archiv
rewind_rollup_watermark‡	Setzt ein Rollup-Watermark zurück, sodass nachfolgende Ticks den Bereich neu aggregieren
backfill_rollup_archive	Stellt einen Hintergrund-Backfill ein, der ein Rollup über die gesamte Historie seines Quellarchivs befüllt oder zurücksetzt
list_recompute_jobs	Listet die letzten Recompute-Jobs eines Rollup-Archivs mit Zustand, Zählern, Laufzeiten und Fehlergrund

Reporting (2)

Tool	Zweck
enable_reporting	Aktiviert den Reporting-Dienst für den Tenant
disable_reporting‡	Deaktiviert den Reporting-Dienst; umkehrbar, Report-Daten bleiben erhalten – Voraussetzung für delete_tenant / detach_tenant

Diagnostik (1)

Tool	Zweck
reconfigure_log_level	Konfiguriert den Log-Level eines Backend-Dienstes zur Laufzeit neu (Identity / Asset / Communication / Reporting / Bot)

Datei-I/O (11 Tools + 2 HTTP-Endpunkte)

Tool	Zweck
prepare_file_upload	Reserviert einen Slot für einen anstehenden Datei-Upload, mit ablaufender URL
cancel_file_transfer	Bricht eine Upload-Reservierung ab oder verwirft einen fertigen Upload-/Download-Puffer
import_ck_model	Importiert ein CK-Modell aus einer hochgeladenen Datei
import_runtime_model	Importiert ein Runtime-Modell aus einer hochgeladenen Datei
export_runtime_model_by_query	Exportiert per Query gematchte Runtime-Entitäten in eine Zip-Datei
export_runtime_model_by_deep_graph	Exportiert einen Deep Graph ausgehend von gegebenen Runtime-IDs in eine Zip-Datei
dump_tenant📁	Erstellt einen Tenant-Dump und veröffentlicht ihn als herunterladbares .tar.gz
restore_tenant‡📁	Stellt einen Tenant aus einer hochgeladenen Dump-Datei wieder her
run_fixup_scripts‡	Startet einen Run-Fixup-Scripts-Job für den Tenant
export_archive_data📁	Exportiert die Zeilen eines Stream-Data-Archivs (optional ein Zeitfenster) als herunterladbares ZIP
import_archive_data📁	Importiert ein exportiertes Archiv-ZIP in ein Zielarchiv mit passendem Schema
HTTP-Endpunkte	PUT /file-transfer/upload/{id} · GET /file-transfer/download/{id} (Range-fähig, 5-GiB-Limit)

Reservierungen und Downloads laufen nach 30 Minuten ab; ein Hintergrund-Sweeper bereinigt sie.

Upload-Ablauf (Import / Restore)

1. prepare_file_upload(fileName)
   → { transferId, uploadUrlPath: "/file-transfer/upload/{transferId}" }
2. HTTP PUT the file body to <publicUrl> + uploadUrlPath
3. import_ck_model(transferId, tenantId)   // or restore_tenant(transferId, ..., confirm: true)
   → waits for the asset/bot job to finish

Download-Ablauf (Export / Dump)

1. dump_tenant(targetTenantId)
   → { transferId, downloadUrlPath: "/file-transfer/download/{transferId}" }
2. HTTP GET <publicUrl> + downloadUrlPath
   → streams bytes with Content-Disposition + range support

Akzeptierte Formate

import_ck_model und import_runtime_model akzeptieren dieselben Formate, die das Asset Repository selbst akzeptiert:

• Ein einzelnes kompiliertes YAML aus bin/<config>/net10.0/octo-ck-libraries/<Project>/out/ck-<name>-<major>.yaml
• Ein einzelnes kompiliertes JSON aus ~/.octo/local-catalog/ck-models/v2/<letter>/<Model>/<major>/ck-<name>-<version>.json
• Ein Zip des Quellordners ConstructionKit/ (ckModel.yaml + types/ + enums/ + attributes/ + associations/ + records/)
• Für Runtime-Modelle: ein einzelnes YAML/JSON, das runtime-model.schema.json entspricht, oder ein Zip davon

Runtime- + Streamdaten-Aggregationen (12)

Tool	Zweck
query_entities_aggregation	Führt eine transiente Aggregationsabfrage über Runtime-Entitäten aus
query_entities_grouping	Führt eine transiente gruppierte Aggregationsabfrage über Runtime-Entitäten aus
query_stream_data_simple	Liest rohe Zeitreihenzeilen aus einem Archiv mit Spaltenprojektion
query_stream_data_aggregation	Führt eine transiente Aggregationsabfrage auf einem Streamdaten-Archiv aus
query_stream_data_grouping	Führt eine transiente gruppierte Aggregationsabfrage auf einem Streamdaten-Archiv aus
query_stream_data_downsampling	Führt eine Downsampling-Abfrage aus, die zeitlich gebucketete Aggregatzeilen zurückgibt
execute_runtime_query	Führt eine persistierte Runtime-Query per RtId aus, mit optionalen Overrides
execute_stream_data_query	Führt eine persistierte Streamdaten-Query per RtId aus, mit optionalen Overrides
get_archive_storage_stats	Ruft archivspezifische Storage-Statistiken massenhaft ab (Zeilenanzahl, Speichergröße, Health)
get_rollup_query_metadata	Gibt Query-Konstruktions-Metadaten für ein Rollup-Archiv zurück
get_archive_coverage	Liefert die gemessene Abdeckung einer Archivfamilie (Basisarchiv und alle Rollups): Bucket-Größe, Ausrichtung, gespeicherte Funktionen, verfügbar von/bis je Stufe
resolve_series_query	Wählt für ein Zeitfenster, eine Ziel-Punktzahl und eine Aggregationsfunktion das abzufragende Archiv oder Rollup (auflösungsabhängiges Routing)

Die Namen der Aggregationsfunktionen sind Kleinbuchstaben-Kurzformen – count, sum, avg, min, max – gewählt, weil LLMs kleingeschriebene SQL-artige Strings zuverlässiger konstruieren als PascalCase-Enum-Namen. Die vollständige Menge der Filteroperatoren ist: Equals, NotEquals, Contains, StartsWith, EndsWith, GreaterThan, GreaterThanOrEqual, LessThan, LessThanOrEqual, Between, In, NotIn, IsNull, IsNotNull, Regex, Like, AnyEq, AnyLike.

Generisches Runtime-CRUD (8)

Tool	Zweck
query_entities	Fragt Entitäten eines beliebigen Construction-Kit-Typs mit optionalen Filtern ab
query_entities_simple	Fragt Entitäten mit einfachen Gleichheitsfiltern ab, für KI-Clients optimiert
get_entity_by_id	Ruft eine einzelne Entität über ihre Runtime-ID ab
create_entity	Erstellt eine neue Entität eines angegebenen Construction-Kit-Typs (lehnt Secret-Werte ab)
create_entity_with_secrets	Erstellt eine Entität zusammen mit ihren Secret-Attributen in einem Insert (Typen mit Pflicht-Secret) — hohes Risiko
update_entity	Aktualisiert eine bestehende Entität (unterstützt Optimistic Locking über expected_version; clearSecretAttributes löscht Secret-Attribute)
delete_entity‡	Löscht eine Entität über ihre Runtime-ID (unterstützt Optimistic Locking)
set_entity_secrets	Setzt, rotiert oder löscht Secret-Attribute einer bestehenden Entität — hohes Risiko

Secret-Attribute

Attribute vom Werttyp SECRET sind nur schreibbar:

• Jedes Tool, das Entitäten liefert (query_entities, get_entity_by_id, navigate_associations, execute_runtime_query, …), zeigt value: null plus secretIsSet: true|false — nie den Wert oder den Chiffretext.
• create_entity / update_entity (mittleres Risiko) lehnen einen nicht leeren Wert für ein Secret-Attribut ab. null, "" oder ein zurückgesendetes { "isSet": … } lassen das gespeicherte Secret unverändert. update_entity akzeptiert clearSecretAttributes (Namen in camelCase oder PascalCase), um optionale Secrets zu löschen.
• set_entity_secrets (rtId, ckTypeId, secrets: [{ attributePath, value }], clearSecretAttributes, expectedVersion, tenantId) setzt, rotiert oder löscht Secrets einer bestehenden Entität. secrets akzeptiert nur Secret-Attribute (Punkt-Notation durch Records, z. B. Endpoints.Token) und lehnt leere Werte ab. Jeder nicht leere Wert — auch einer, der wie ein Platzhalter aussieht (<…>, TODO_SET_*) — wird als Secret gespeichert.
• create_entity_with_secrets (ckTypeId, entityData, secrets, tenantId) erstellt eine Entität zusammen mit ihren Secrets in einem Insert. Es ist für CK-Typen mit einem Pflicht-Secret gedacht: Der Server lehnt das Anlegen einer solchen Entität ohne Wert ab, daher kann create_entity gefolgt von set_entity_secrets sie nicht anlegen. Für entityData gelten die Regeln von create_entity, für secrets die von set_entity_secrets.
• Nur diese beiden Tools mit hohem Risiko schreiben einen Secret-Wert.
• Filter auf einem Secret unterstützen nur IsNull / IsNotNull. Andere Filteroperatoren, Aggregationen und Group-by auf einem Secret werden mit SecretAttributeNotQueryable abgelehnt; get_available_archive_paths listet nie Secrets.

Secret-Wartung (4)

Tool	Zweck
get_secret_status	Verschlüsselungsstatus eines Tenants (allTenants: true: jedes Tenants) — Umgebungsstatus (Key Ring konfiguriert, aktive und bekannte Key-IDs, strikter Modus, Verify-Cron, letzter Verify), die letzten Sweep-Läufe mit ihrem Dump-Zustand, der letzte Bericht mit Anzahlen pro Form und Key-ID und den nicht lesbaren, neu einzugebenden Werten; nie Werte
start_secret_sweep	Startet einen Sweep-Job: mode = Verify (Standard), Encrypt, Reprotect oder CleanupUnreadable; Encrypt, Reprotect und CleanupUnreadable brauchen confirm: true (wird an den Server weitergegeben); optional waitForCompletion. Decrypt wird abgelehnt — hohes Risiko
get_secret_inventory	Listet die Secret-Attribut-Slots eines Tenants (Entity, Attributpfad, Pflicht, Speicherform) aus der Secrets-Übersicht; nie Werte
restore_secret_sweep_dump‡	Spielt den vor einem Secret-Sweep erstellten Dump in seinen Tenant zurück (ersetzt die Tenant-Datenbank) — hohes Risiko

Die Modi beschreibt Secret Encryption Key Ring. Die Secrets-Übersicht gibt es auch als GraphQL-Abfrage secrets { inventory … } (Rolle AdminPanelManagement).

Schema-Discovery (7)

Tool	Zweck
get_available_models	Listet alle im System verfügbaren Construction-Kit-Modelle auf
get_available_types	Listet alle CK-Typen mit ihren grundlegenden Metadaten auf
get_type_schema	Ruft das detaillierte Schema für einen bestimmten CK-Typ ab
search_types	Durchsucht CK-Typen nach Name oder Beschreibung
get_association_tree	Gibt den Assoziationsbaum ausgehend von einem gegebenen CK-Typ zurück
navigate_associations	Navigiert Assoziationen zwischen Entitäten
get_available_archive_paths	Gibt die von einem CK-Typ aus erreichbaren Attributpfade zurück – verwendet von Archiv-Spaltenauswählern

Server-Management (6)

Tool	Zweck
list_available_tools	Listet jedes Tool auf, das der Server aktuell anbietet
get_tool_details	Ruft die vollständigen Details (Parameter, Beispiele) für ein bestimmtes Tool ab
get_tool_risk_metadata	Ruft die Risikoklassifizierungs-Metadaten für alle Tools ab
get_tool_statistics	Ruft Ausführungsstatistiken und Nutzungsmetriken ab
validate_tool_parameters	Prüft einen Parametersatz gegen das Schema eines Tools, ohne es auszuführen
Echo	Gibt die Eingabe an den Client zurück (Smoke-Test)

Optimistic Locking bei Schreibvorgängen

update_entity und delete_entity akzeptieren ein optionales expected_version (die RtVersion, die Sie bei Ihrem vorherigen Lesen beobachtet haben). Drei Verhaltensweisen:

expected_version	Ergebnis
Weggelassen	Last-Write-Wins. update_entity erhöht dennoch RtVersion, sodass ein späterer optimistischer Aufruf ein sinnvolles Token sieht.
Stimmt mit gespeichertem überein	Schreiben/Löschen wird durchgeführt; die Antwort trägt die erhöhte CurrentRtVersion.
Veraltet	Kein Schreiben. Die Antwort ist IsSuccess: false, IsConflict: true, plus das aktuelle Entity-Payload, sodass der Aufrufer ohne ein zweites get_entity_by_id rebasen kann.

Aufrufer-Muster:

read = get_entity_by_id(...)            // read.entity.rtVersion = 7
edit = mutate(read.entity)
res  = update_entity(..., expected_version: 7)
if (res.is_conflict) {
    edit2 = merge(res.entity, ...)
    update_entity(..., expected_version: res.current_rt_version)
}

Generierung eigener Apps (6)

Tools für KI-Agenten, die aus dem Template-Repository eine eigene OctoMesh-Web-App aufsetzen.

Tool	Zweck
get_custom_app_template_manifest	Manifest der kanonischen Dateien im Custom-App-Template (welche Dateien bearbeitet werden, welche generiert sind)
list_kendo_components	Katalog der im Template fixierten Kendo-Angular-Komponenten mit Paketen, Import-Symbolen und Hinweisen
plan_custom_app_scaffold	Erstellt einen Scaffold-Plan (Seiten, Drawer-Einträge, Routen, Dateipfade) für eine neue Custom App
apply_custom_app_scaffold	Setzt einen Plan in Dateiinhalte und Routen-/Drawer-Änderungen um, die der Agent schreibt
export_runtime_graphql_sdl	Exportiert das aktuelle Runtime-GraphQL-Schema des Tenants als Datei für die Codegenerierung
create_tenant_app_repo	Legt ein GitHub-Repository für die Custom App eines Tenants an

Risikoklassifizierung

Tools tragen eine [McpRisk(Low|Medium|High)]-Klassifizierung (ein Tool ohne explizites Attribut gilt als Low), die umschließende Clients (insbesondere der OctoMesh AI Adapter) beim Sitzungsstart über get_tool_risk_metadata lesen. Es handelt sich um informative Metadaten, nicht um einen Autorisierungsmechanismus (die Autorisierung liegt in den Backend-Diensten über das weitergereichte OAuth-Token).

Level	Beispiele	Verhalten des umschließenden Clients
Low (Standard)	Lesevorgänge, Schema-Introspektion, Einzel-Instanz-Create/Update	Läuft stillschweigend
Medium	Einzel-Instanz-Deletes, durch Schema-Introspektion getriebene Aktionen	Protokollieren; nicht pausieren
High	Massen-Deletes, Verwerfen eines CK-Typs/-Attributs/-Enum-Werts, Produktions-Deploy, Blueprint-Install/-Uninstall/-Apply-Update, Setzen von Secrets (set_entity_secrets, create_entity_with_secrets, add_oauth_identity_provider, add_azure_entra_id_identity_provider, update_identity_provider, start_secret_sweep)	Pausieren und den vorgeschlagenen Aufruf zur Benutzerfreigabe anzeigen

Die Klassifizierung ist pro Tool statisch. Deshalb schreiben nur eigene Tools mit hohem Risiko Secret-Werte, während das generische create_entity / update_entity mittleres Risiko behält und Secret-Werte ablehnt.

Ausgearbeitete Beispiele

Child-Tenants auflisten

{ "tool": "get_tenants", "parameters": { "tenantId": "octosystem" } }

Einen Sub-Tenant erstellen und den aufrufenden Benutzer als Admin provisionieren

{ "tool": "create_tenant",                       "parameters": { "childTenantId": "acme", "database": "acme_db" } }
{ "tool": "provision_current_user_as_admin",     "parameters": { "targetTenantId": "acme" } }

Eine neue Chart-Version über alle passenden Workloads ausrollen

{ "tool": "get_workloads_by_chart",          "parameters": { "chartName": "octo-mesh-adapter" } }
{ "tool": "update_workload_chart_version",   "parameters": { "workloadId": "wl-123", "chartVersion": "1.2.4" } }
{ "tool": "deploy_workload",                 "parameters": { "workloadId": "wl-123" } }

Sensormesswerte gruppiert nach Facility aggregieren

{
  "tool": "query_entities_grouping",
  "parameters": {
    "ckTypeId": "Industry.Energy-1/Sensor-1",
    "groupByAttributePaths": ["FacilityId", "Region"],
    "aggregations": [
      { "function": "count" },
      { "function": "avg", "attributePath": "Power", "alias": "avgPower" },
      { "function": "max", "attributePath": "Power", "alias": "peakPower" }
    ]
  }
}

Ein Sensorarchiv in Stundenbuckets downsamplen

{
  "tool": "query_stream_data_downsampling",
  "parameters": {
    "archiveRtId": "69fda707d47638c68edc7fea",
    "aggregations": [
      { "function": "avg", "attributePath": "Power" },
      { "function": "max", "attributePath": "Power", "alias": "peak" }
    ],
    "from": "2026-06-01T00:00:00Z",
    "to":   "2026-06-08T00:00:00Z",
    "limit": 168
  }
}

Eine im Studio erstellte persistierte Runtime-Query erneut abspielen

{
  "tool": "execute_runtime_query",
  "parameters": {
    "queryRtId": "70a3e9c1d28b8a0f5c1c79bd",
    "extraFilters": {
      "operator": "And",
      "fields": [{ "attributePath": "Region", "operator": "Equals", "value": "EU" }]
    }
  }
}

extraFilters wird per AND mit dem Filter der persistierten Query kombiniert; das Tool dispatcht anhand des Subtyps der persistierten Query (RtSimpleRtQuery / RtAggregationRtQuery / RtGroupingAggregationRtQuery) und projiziert das Ergebnis entsprechend.