Tool reference

The MCP (Model Context Protocol) Services exposes ~177 tools as of version 1.5.3, grouped into the families below. Most platform-admin tools mirror the matching octo-cli command (snake_case names — e.g. CLI CreateTenant → MCP create_tenant); the aggregation and persisted-query tools mirror the asset-repository's GraphQL transient-query surface.

Notation in this reference:

^‡ — destructive, requires confirm: true
^📁 — uses the file-transfer endpoints
All tenant-scoped tools accept an optional tenantId parameter (falls back to URL route)

You can always discover the live catalogue from a connected client:

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

Authentication & identity bootstrap (5)

Tool	Purpose
`authenticate`	Start OAuth2 Device Authorization Flow — returns verification URL and user code
`check_auth_status`	Check whether the browser login has completed
`auth_status`	Show authentication status; optionally refresh an expired access token
`whoami`	Return the authenticated user (name, email, roles, tenants)
`list_tenants`	List every tenant the authenticated user has access to

Tenant lifecycle (10)

Tool	Purpose
`get_tenants`	List child tenants visible from the parent tenant
`create_tenant`	Create a new child tenant under the parent
`delete_tenant`^‡	Delete a child tenant
`clean_tenant`^‡	Reset a child tenant to factory defaults
`attach_tenant`	Attach an existing database as a child tenant without creating new data
`detach_tenant`	Detach a child tenant while preserving its database
`clear_tenant_cache`^‡	Clear the in-memory caches of a child tenant
`update_system_ck_model`	Update the system Construction Kit model of a child tenant to the current version
`dump_tenant`^📁	Create a dump of the tenant's data and publish it as a downloadable `.tar.gz`
`restore_tenant`^‡📁	Restore a tenant from an uploaded dump file

Identity — users (7)

Tool	Purpose
`get_users`	List users in the tenant
`create_user`	Create a new user account, optionally with an initial password
`update_user`	Update an existing user's email and/or username
`delete_user`^‡	Delete a user account
`reset_user_password`^‡	Reset a user's password
`add_user_to_role`	Assign a role to a user
`remove_user_from_role`^‡	Remove a role from a user

Identity — roles (4)

Tool	Purpose
`get_roles`	List roles in the tenant
`create_role`	Create a new role
`update_role`	Rename an existing role
`delete_role`^‡	Delete a role

Identity — groups (10)

Tool	Purpose
`get_groups`	List groups in the tenant
`get_group`	Get a single group by runtime ID
`create_group`	Create a new group, optionally with description and role assignments
`update_group`	Update group metadata (name, description)
`delete_group`^‡	Delete a group
`update_group_roles`	Replace all role assignments on a group
`add_user_to_group`	Add a user to a group
`remove_user_from_group`^‡	Remove a user from a group
`add_group_to_group`	Nest a child group inside a parent group
`remove_group_from_group`^‡	Un-nest a child group from its parent

Identity — OAuth clients (13)

Tool	Purpose
`get_clients`	List OAuth clients in the tenant
`get_client`	Get a single OAuth client by client ID
`add_client_credentials_client`	Create an OAuth client with grant type `client_credentials`
`add_device_code_client`	Create an OAuth client with grant type `device_code`
`add_authorization_code_client`	Create an OAuth client with grant type `authorization_code`
`delete_client`^‡	Delete an OAuth client
`add_scope_to_client`	Grant a scope to a client by appending to its `AllowedScopes`
`get_client_mirrors`	List child tenants the flagged ClientCredentials client has been mirrored into
`provision_client_in_existing_tenants`	Back-fill a flagged client into every existing sub-tenant
`provision_client_in_tenant`	Provision a client into a single named sub-tenant
`unprovision_client_from_tenant`^‡	Remove a client mirror from a sub-tenant
`set_client_auto_provision`	Toggle the `AutoProvisionInChildTenants` flag on an existing client

Identity — identity providers (8)

Tool	Purpose
`get_identity_providers`	List identity providers in the tenant
`update_identity_provider`	Update common fields on an existing identity provider
`delete_identity_provider`^‡	Delete an identity provider
`add_oauth_identity_provider`	Create a Google, Microsoft, or Facebook OAuth identity provider
`add_azure_entra_id_identity_provider`	Create an Azure Entra ID identity provider
`add_open_ldap_identity_provider`	Create an OpenLDAP identity provider
`add_active_directory_identity_provider`	Create a Microsoft Active Directory identity provider
`add_octo_tenant_identity_provider`	Create an OctoTenant identity provider for cross-tenant auth

Identity — API resources, scopes, secrets (16)

Tool	Purpose
`get_api_resources`	List OAuth API resources in the tenant
`create_api_resource`	Create a new OAuth API resource
`update_api_resource`	Update an existing OAuth API resource
`delete_api_resource`^‡	Delete an OAuth API resource
`get_api_scopes`	List OAuth API scopes in the tenant
`create_api_scope`	Create a new OAuth API scope
`update_api_scope`	Update an existing OAuth API scope
`delete_api_scope`^‡	Delete an OAuth API scope
`get_client_secrets`	List API secrets attached to a client
`create_client_secret`	Create a new API secret on a client
`update_client_secret`	Update a client secret
`delete_client_secret`^‡	Delete a client secret
`get_api_resource_secrets`	List API secrets attached to an API resource
`create_api_resource_secret`	Create a new API secret on an API resource
`update_api_resource_secret`	Update an API resource secret
`delete_api_resource_secret`^‡	Delete an API resource secret

Identity — cross-tenant mappings & admin provisioning (14)

Tool	Purpose
`get_email_domain_group_rules`	List email-domain group rules
`get_email_domain_group_rule`	Get a single email-domain group rule by runtime ID
`create_email_domain_group_rule`	Create a rule that auto-adds matching users to a group
`update_email_domain_group_rule`	Update an email-domain group rule
`delete_email_domain_group_rule`^‡	Delete an email-domain group rule
`get_external_tenant_user_mappings`	List external-tenant user mappings, with optional filter
`get_external_tenant_user_mapping`	Get a single external-tenant user mapping by runtime ID
`create_external_tenant_user_mapping`	Create a new external-tenant user mapping
`update_external_tenant_user_mapping`	Update role assignments on an external-tenant user mapping
`delete_external_tenant_user_mapping`^‡	Delete an external-tenant user mapping
`get_admin_provisioning_mappings`	List admin-provisioning mappings for the target tenant
`create_admin_provisioning_mapping`	Create a new admin-provisioning mapping
`provision_current_user_as_admin`	Provision the calling user as admin in the target tenant via a mapping
`delete_admin_provisioning_mapping`^‡	Delete an admin-provisioning mapping

Asset repository — blueprints (10)

Tool	Purpose
`list_blueprints`	List blueprints available across the configured catalogs (paginated)
`install_blueprint`	Apply a blueprint to a tenant for the first time, with optional force re-apply
`get_blueprint_history`	Return the blueprint application history for a tenant in chronological order
`get_blueprint_update_info`	Return update info for the tenant's current blueprint
`preview_blueprint_update`	Preview the changes a blueprint update would apply, without applying them
`update_blueprint`^‡	Apply a blueprint update (destructive unless `dryRun=true`)
`list_blueprint_backups`	List backups created before blueprint updates
`rollback_blueprint`^‡	Roll a tenant back to a previously-created blueprint backup
`list_blueprint_installations`	List blueprints currently installed on a tenant
`uninstall_blueprint`^‡	Remove a blueprint from a tenant

Asset repository — CK model libraries (8)

Tool	Purpose
`list_ck_catalogs`	List the CK model catalog sources configured for the asset service
`list_ck_catalog_models`	List models available in catalogs, with optional filter
`refresh_ck_catalogs`	Refresh the CK model catalog caches
`get_ck_library_status`	Get the merged library status for a tenant with update flags
`check_ck_dependencies`	Resolve dependencies for a catalog model
`check_ck_upgrade`	Pre-flight check for upgrading/migrating an installed CK model
`import_ck_from_catalog`	Import a CK model from the catalog, including all dependencies
`fix_all_ck_models`^‡	Find every installed CK model needing update/fix and enqueue imports

Service-managed CK models

import_ck_from_catalog silently no-ops for service-managed models (System.*, e.g. System.Communication, System.StreamData, System.Reporting). Use the matching enable_<feature> tool instead — see Troubleshooting.

Communication controller (28)

Lifecycle (2)

Tool	Purpose
`enable_communication`	Enable the communication controller for the tenant
`disable_communication`^‡	Disable the communication controller

Adapters (4)

Tool	Purpose
`get_adapters`	List adapters configured for the tenant
`get_adapter`	Get the full configuration of a single adapter
`get_adapter_nodes`	Return aggregated pipeline-node descriptors from all connected adapters
`get_pipeline_schema`	Return the composite pipeline JSON Schema for a given adapter

Pipelines (10)

Tool	Purpose
`get_pipeline_status`	Get the deployment state of a pipeline
`deploy_pipeline`	Deploy a pipeline definition (YAML or JSON string) to an adapter
`validate_pipeline_definition`	Validate a pipeline definition against the adapter's composite schema
`execute_pipeline`	Execute a pipeline and return the execution ID
`dry_run_pipeline`	Execute a pipeline in dry-run mode, suppressing Load-node side effects
`set_pipeline_debug`	Enable or disable debug capture for a pipeline
`get_pipeline_debug`	Get the persisted debug state of a pipeline
`get_pipeline_executions`	Return the pipeline's execution history
`get_latest_pipeline_execution`	Return the most recent pipeline execution
`get_pipeline_debug_points`	Return debug-point nodes for a specific pipeline execution

Data flows, triggers, pools (6)

Tool	Purpose
`deploy_data_flow`	Deploy a data flow
`undeploy_data_flow`^‡	Undeploy a data flow
`get_data_flow_status`	Get the aggregated execution status of a data flow
`deploy_triggers`	Deploy all pipeline triggers for the tenant
`undeploy_triggers`^‡	Undeploy all pipeline triggers
`get_pools`	List pools configured for the tenant

Workloads & CI/CD rollout (5)

Tool	Purpose
`get_workloads_by_chart`	List workloads in the tenant whose `ChartName` matches the given name
`update_workload_chart_version`	Set the `ChartVersion` on a workload without triggering a deploy
`deploy_workload`	Trigger a deploy of a workload through its parent pool
`undeploy_workload`^‡	Trigger an undeploy of a workload
`move_pipelines`^‡	Bulk-reassign pipelines from the current adapter to a new target

Time series, reporting, diagnostics (14)

Stream data & archives (11)

Tool	Purpose
`enable_stream_data`	Enable Stream Data ingestion for the tenant
`disable_stream_data`^‡	Disable Stream Data ingestion
`activate_archive`	Activate a `CkArchive` by provisioning its per-archive CrateDB table
`disable_archive`	Disable a `CkArchive` (data preserved, transitions to Disabled)
`enable_archive`	Re-enable a previously disabled archive
`retry_archive_activation`	Retry archive activation after a DDL failure
`delete_archive`^‡	Drop the per-archive CrateDB table
`list_rollups_for_archive`	List every rollup archive attached to a source `CkArchive`
`freeze_rollup_archive`	Freeze a rollup archive at a given timestamp
`unfreeze_rollup_archive`	Clear `FrozenUntil` on a rollup archive
`rewind_rollup_watermark`^‡	Reset a rollup watermark so subsequent ticks re-aggregate the range

Reporting (2)

Tool	Purpose
`enable_reporting`	Enable the reporting service for the tenant
`disable_reporting`^‡	Disable the reporting service

Diagnostics (1)

Tool	Purpose
`reconfigure_log_level`	Reconfigure a backend service's log level at runtime (Identity / Asset / Communication / Reporting / Bot / AdminPanel)

File I/O (9 tools + 2 HTTP endpoints)

Tool	Purpose
`prepare_file_upload`	Reserve a slot for an upcoming file upload, with expiration URL
`cancel_file_transfer`	Cancel an upload reservation or discard a finished upload/download buffer
`import_ck_model`	Import a CK model from an uploaded file
`import_runtime_model`	Import a runtime model from an uploaded file
`export_runtime_model_by_query`	Export runtime entities matched by a query to a zip file
`export_runtime_model_by_deep_graph`	Export a deep graph starting from given runtime IDs to a zip file
`dump_tenant`^📁	Create a tenant dump and publish it as a downloadable `.tar.gz`
`restore_tenant`^‡📁	Restore a tenant from an uploaded dump file
`run_fixup_scripts`^‡	Start a run-fixup-scripts job for the tenant
HTTP endpoints	`PUT /file-transfer/upload/{id}` · `GET /file-transfer/download/{id}` (range-enabled, 5 GiB cap)

Reservations and downloads expire after 30 minutes; a background sweeper purges them.

Upload flow (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 flow (export / dump)

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

Accepted formats

import_ck_model and import_runtime_model accept the same formats that the asset repository itself accepts:

A single compiled YAML from bin/<config>/net10.0/octo-ck-libraries/<Project>/out/ck-<name>-<major>.yaml
A single compiled JSON from ~/.octo/local-catalog/ck-models/v2/<letter>/<Model>/<major>/ck-<name>-<version>.json
A zip of the source ConstructionKit/ folder (ckModel.yaml + types/ + enums/ + attributes/ + associations/ + records/)
For runtime models: a single YAML/JSON conforming to runtime-model.schema.json, or a zip thereof

Runtime + stream-data aggregations (10)

Tool	Purpose
`query_entities_aggregation`	Execute a transient aggregation query over runtime entities
`query_entities_grouping`	Execute a transient grouped-aggregation query over runtime entities
`query_stream_data_simple`	Read raw time-series rows from an archive with column projection
`query_stream_data_aggregation`	Execute a transient aggregation query on a stream-data archive
`query_stream_data_grouping`	Execute a transient grouped-aggregation query on a stream-data archive
`query_stream_data_downsampling`	Execute a downsampling query returning time-bucketed aggregate rows
`execute_runtime_query`	Execute a persisted runtime query by RtId, with optional overrides
`execute_stream_data_query`	Execute a persisted stream-data query by RtId, with optional overrides
`get_archive_storage_stats`	Bulk-fetch per-archive storage stats (row count, disk size, health)
`get_rollup_query_metadata`	Return query-construction metadata for a rollup archive

Aggregation function names are lowercase short forms — count, sum, avg, min, max — chosen because LLMs construct lowercase SQL-style strings more reliably than PascalCase enum names. The full set of filter operators is: Equals, NotEquals, Contains, StartsWith, EndsWith, GreaterThan, GreaterThanOrEqual, LessThan, LessThanOrEqual, Between, In, NotIn, IsNull, IsNotNull, Regex, Like, AnyEq, AnyLike.

Generic runtime CRUD (6)

Tool	Purpose
`query_entities`	Query entities of any Construction Kit type with optional filters
`query_entities_simple`	Query entities with simple equality filters, optimised for AI clients
`get_entity_by_id`	Get a single entity by its runtime ID
`create_entity`	Create a new entity of a specified Construction Kit type
`update_entity`	Update an existing entity (supports optimistic locking via `expected_version`)
`delete_entity`^‡	Delete an entity by its runtime ID (supports optimistic locking)

Schema discovery (7)

Tool	Purpose
`get_available_models`	List all Construction Kit models available in the system
`get_available_types`	List all CK types with their basic metadata
`get_type_schema`	Get the detailed schema for a specific CK type
`search_types`	Search CK types by name or description
`get_association_tree`	Return the association tree rooted at a given CK type
`navigate_associations`	Navigate associations between entities
`get_available_archive_paths`	Return the attribute paths reachable from a CK type — used by archive column pickers

Server management (5)

Tool	Purpose
`list_available_tools`	List every tool the server currently advertises
`get_tool_details`	Get the full detail (parameters, examples) for a specific tool
`get_tool_risk_metadata`	Get risk classification metadata for all tools
`get_tool_statistics`	Get execution statistics and usage metrics
`Echo`	Echo input back to client (smoke test)

Optimistic locking on writes

update_entity and delete_entity accept an optional expected_version (the RtVersion you observed on your prior read). Three behaviours:

`expected_version`	Result
Omitted	Last-write-wins. `update_entity` still bumps `RtVersion`, so a later optimistic call sees a meaningful token.
Matches stored	Write/delete proceeds; response carries the bumped `CurrentRtVersion`.
Stale	No write. Response is `IsSuccess: false`, `IsConflict: true`, plus the current `Entity` payload so the caller can rebase without a second `get_entity_by_id`.

Caller pattern:

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)
}

Risk classification

Every tool carries an [McpRisk(Low|Medium|High)] classification that wrapping clients (notably the OctoMesh AI Adapter) read at session start via get_tool_risk_metadata. It is informational metadata, not an authorisation mechanism (authorisation lives in the backend services via the propagated OAuth token).

Level	Examples	Wrapping-client behaviour
Low (default)	Reads, schema introspection, single-instance create/update	Run silently
Medium	Single-instance deletes, schema-introspection-driven actions	Log; do not pause
High	Bulk deletes, dropping a CK type/attribute/enum value, production deploy, blueprint install/uninstall/apply-update	Pause and surface the proposed call for user approval

Worked examples

List child tenants

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

Create a sub-tenant and provision the calling user as admin

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

Roll out a new chart version across all matching workloads

{ "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" } }

Aggregate sensor readings grouped by facility

{
  "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" }
    ]
  }
}

Downsample a sensor archive into hourly buckets

{
  "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
  }
}

Replay a persisted runtime query authored in the Studio

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

extraFilters is AND-combined with the persisted query's filter; the tool dispatches on the persisted query subtype (RtSimpleRtQuery / RtAggregationRtQuery / RtGroupingAggregationRtQuery) and projects the result accordingly.

Authentication & identity bootstrap (5)​

Tenant lifecycle (10)​

Identity — users (7)​

Identity — roles (4)​

Identity — groups (10)​

Identity — OAuth clients (13)​

Identity — identity providers (8)​

Identity — API resources, scopes, secrets (16)​

Identity — cross-tenant mappings & admin provisioning (14)​

Asset repository — blueprints (10)​

Asset repository — CK model libraries (8)​

Communication controller (28)​

Lifecycle (2)​

Adapters (4)​

Pipelines (10)​

Data flows, triggers, pools (6)​

Workloads & CI/CD rollout (5)​

Time series, reporting, diagnostics (14)​

Stream data & archives (11)​

Reporting (2)​

Diagnostics (1)​

File I/O (9 tools + 2 HTTP endpoints)​

Upload flow (import / restore)​

Download flow (export / dump)​

Accepted formats​

Runtime + stream-data aggregations (10)​

Generic runtime CRUD (6)​

Schema discovery (7)​

Server management (5)​

Optimistic locking on writes​

Risk classification​

Worked examples​

List child tenants​

Create a sub-tenant and provision the calling user as admin​

Roll out a new chart version across all matching workloads​

Aggregate sensor readings grouped by facility​

Downsample a sensor archive into hourly buckets​

Replay a persisted runtime query authored in the Studio​