Docs

Operate

AI agents and MCP

How AI agents work with a Konstrukt tenant — the embedded MCP server, its knowledge resources and tenant documents, the full tool catalogue, safe working rules, the in-product assistant Kai, and the agent-readable sources of this documentation.

Every Konstrukt tenant embeds a Model Context Protocol (MCP) server in its API. An MCP-capable agent connected to it can read and build the whole model — plans, dimensions, value types, calculations, references, apps and access rules — import data, and validate and run Kex scripts, within the privileges of the user it acts as. The server also ships the knowledge an agent needs to write correct Kex and app configuration. Inside the product, the assistant Kai uses the same authoring rules.

The MCP server#

Property Value
Endpoint https://{tenant}.konstrukt.app/api/mcp
Scope One tenant per server; the caller's own user
Tool filtering Tools are filtered by the caller's privileges
Plan access Plan-scoped operations check the caller's access to that plan
Server instructions Sent on connect: core concepts, where the knowledge resources are, working rules

Identifiers#

Object ID type Example
Value type String "Amount"
Dimension String "Department"
Plan Integer 3
Calculation Integer 101
Dimension property Integer (also has code and name) 9905
App GUID string "7c1e…"
Import configuration Key (GUID) —

isLegacy appears on plans only when the tenant still has legacy (v1) plans; most tenants have only v2 plans. App-config writing is supported for v2 plans only.

Authentication and access#

  • An MCP client signs in through the browser with an API key: the Key ID and API key are entered as client ID and client secret in a web sign-in. The key belongs to a user account, and the MCP session carries that user's permissions.
  • After the move to the new hosting environment (autumn 2026), MCP clients will instead authenticate with the tenant's ordinary sign-in methods, such as Microsoft and Google accounts. See Sign-in.
  • MCP access is currently available to administrators.

Tested clients: Claude, ChatGPT, Microsoft Copilot, Google Gemini and OpenCode, including OpenCode with models hosted by Berget AI.

Connecting a client#

  1. In the MCP client, add a remote MCP server (connector) with the URL https://{tenant}.konstrukt.app/api/mcp.
  2. Connect. The client opens a Konstrukt sign-in page in the browser.
  3. Sign in with an API key: enter the Key ID as client ID and the API key as client secret. See Machine credentials.
  4. The client lists the tools and resources the account has access to. Start with konstrukt://TenantInstructions.md, see Working rules.

Integrations that call the REST API directly use the same key pair as client ID and client secret in the client_credentials grant. See REST API.

Knowledge resources#

Platform knowledge is exposed as MCP protocol resources (resources/list, resources/read):

URI Content When to load
konstrukt://resources/kex/KexOverview.md Short structural overview of Kex: clause skeleton, implicit resolution, identifiers, expansion First, for most syntax questions
konstrukt://resources/kex/KexDocumentation.md Complete Kex language reference Only when the overview is not enough
konstrukt://resources/kex/KexGuidelines.md Authoring rules: clause order, minimal scripts, validate before returning, disambiguation Before writing scripts
konstrukt://resources/kex/KexKnowledge.md Known pitfalls (custom grouping duplication, windowing over un-aggregated value types) Before windowed or grouped scripts
konstrukt://resources/kex/KexScriptExamples.md A few minimal examples Optional
konstrukt://resources/kex/GeneralInstructions.md Concept definitions: plan, dimension, property, value type, dataset, calculation, app When unsure of a concept
konstrukt://schema/app-config JSON Schema (draft 2020-12) for app configuration, about 123,000 characters For clients that can attach resources; agents should read the types they need with get_app_config_schema instead
konstrukt://TenantInstructions.md Tenant-specific instructions and links to tenant documents At the start of any work on a tenant
konstrukt://tenant/{name} Tenant-authored documents As linked from TenantInstructions.md

The human-readable equivalents are Kex, the Kex reference at https://acme.konstrukt.app/api/documentation/kex (served by every tenant at the same path) and App configuration.

Tenant knowledge base#

A tenant can publish its own conventions for agents: naming rules, which plan holds what, how a recurring refresh is done.

  • save_mcp_resource(name, content, description) creates or replaces a document. Names may contain / for folders (plans/sales.md); allowed characters are a-z A-Z 0-9 . - _ ~ and /. Documents appear as konstrukt://tenant/{name}.
  • Saving TenantInstructions.md rewrites the tenant instructions sent to clients. It cannot be deleted; save empty content to stop sending instructions.
  • delete_mcp_resource deletes a document permanently.
  • A proven pattern: one document per plan under plans/, each linked from TenantInstructions.md, stating the plan's dimensions, code conventions, known data quirks and the exact refresh procedure.

Two resource surfaces

The tools list_mcp_resources and get_mcp_resource only see tenant documents (TenantInstructions.md and documents saved with save_mcp_resource). The platform resources under konstrukt://resources/kex/ and the schema are read through the MCP protocol's resources/read, not through get_mcp_resource.

Tool catalogue#

A caller with full privileges currently sees 61 tools.

Plans#

Tool Purpose
list_plans All accessible plans, active and archived: id, name, isActive, isDefault (and isLegacy if applicable)
get_data_model Metadata for one or more plans; include = *, (none) or entity names ValueTypes, Dimensions, DimensionProperties, Calculations
create_plan New plan, optionally a copy of an active plan (copyFromPlanId)
update_plan Rename a plan (only provided fields change)
archive_plan Set a plan inactive; required before deletion
delete_plan Permanently delete an archived plan

Dimensions and properties#

Tool Purpose
list_dimensions Dimensions of a plan
create_dimension · update_dimension · delete_dimension Dimension CRUD (id, name, description)
list_dimension_properties Properties of a dimension: id, code, name, description
create_dimension_property New property; bindToDimensionId binds it to another dimension
update_dimension_property · delete_dimension_property Property CRUD
insert_dimension_data · update_dimension_data · upsert_dimension_data Import dimension values (insert-only, update-only, upsert); autoCreatePropertyValues
insert_dimension_property_data · update_dimension_property_data · upsert_dimension_property_data Import property values; property identified by propertyIdentifier (name, then code, then ID)

Value types and data#

Tool Purpose
list_value_types Value types of a plan
create_value_type · update_value_type · delete_value_type Value type CRUD: id, name, dimensionIds[], formatCode, viewPrecision, editPrecision, isSensitive, description
insert_value_type_data · update_value_type_data · upsert_value_type_data Import plan or reference data
replace_value_type_data Insert, update and delete rows not in the payload
delete_value_type_data Delete rows matching an uploaded filter file
import_data Run a pre-defined import configuration by key

References#

Tool Purpose
list_references References of a plan: id, name
create_reference Data reference, or point-in-time reference when pointInTime is given
update_reference Update a reference; a data reference cannot become point-in-time or vice versa
delete_reference Delete a reference and its reference data

Calculations#

Tool Purpose
list_calculations Calculations with script, isEnabled, isValid, validationMessages[]
create_calculation · update_calculation · delete_calculation CRUD with server-side validation; update_calculation also takes enabled
get_calculation_graph Dependency graph: per calculation level, references[], outputs[], dependsOn[]; filter by planIds, referencedEntityIds, outputEntityIds
get_running_calculations Running or enqueued calculations in one plan
get_all_running_calculations Running or enqueued calculations across plans (plan ID → calculation IDs)

Scripts#

Tool Purpose
validate_script Validate a Kex script without executing it
execute_read_script Run a read-only script; returns one or more named result sets
execute_write_script Run a script that may modify data; write result sets report Inserted, Updated, Deleted

Apps#

Tool Purpose
list_apps Apps in a plan: id (GUID), name, description
search_app_config Find parts of an app's configuration by JSONPath or JSON Pointer, with the pointer of each match
load_complete_app_config Read an app's whole configuration as JSON, with an etag (v1 and v2)
patch_app_config Change parts of a configuration with a JSON Patch; dryRun and ifMatch supported (v2 only)
overwrite_complete_app_config Replace a whole configuration (v2 only)
validate_complete_app_config Validate a configuration without saving (v1 and v2)
create_app_with_config Create an app and write its configuration in one call (v2 only); name and description are parameters, not part of the JSON
delete_app Permanently delete an app and all its data

Access#

Tool Purpose
get_users Active users with roles, plan access and user type
get_groups · get_roles Groups with their roles; roles with their groups
get_access_rules Rules of one access list (planId, accessListId)
import_users Import users (default mode Insert); creates no logins — for SSO tenants
import_groups · import_roles · import_access_rules Import with mode Insert, Update, Upsert (default) or Replace

MCP resources#

Tool Purpose
list_mcp_resources List tenant documents
get_mcp_resource Read a tenant document by name
save_mcp_resource Create or replace a tenant document (including TenantInstructions.md)
delete_mcp_resource Delete a tenant document (not TenantInstructions.md)

Documentation and schema#

Tool Purpose
list_documentation List the platform documentation pages
read_documentation Read a page by uri, konstrukt://resources/docs/<page>.md
get_app_config_schema Describe app-config types. Without types, the root (AppConfigModel) and every type name; with types, each type's properties, which are required, the $type of each variant and the types they refer to. Use it before building any app-config payload

Not available through MCP#

Flows, precalculation configuration, creating or listing access lists, integration configurations and jobs, cell comments, app rename or copy, API keys, themes and feature flags. Use the admin GUI for these.

Tools follow privileges

The tool list is filtered by the signed-in user's privileges. An agent should treat a missing tool as a permission boundary, not as an error to work around.

Data import parameters#

The insert_*, update_*, upsert_*, replace_* and delete_* data tools share these parameters:

Parameter Meaning
contentType text/csv (semicolon-separated), text/tab-separated-values, or application/vnd.openxmlformats-officedocument.spreadsheetml.sheet (shorthand application/vnd.ms-excel) for xlsx
data File content as a string (or request body)
fieldMappings Comma-separated, index-based target per column; empty entry skips the column. Value type files: Value and dimension IDs. Dimension files: Code, Name, property names
sheetName Sheet for xlsx
planId Target plan; null = default plan
referenceId / referenceName Write reference data instead of plan data
aggregation Duplicate rows: Sum, Min, Max, Avg, Concatenate, Disabled
autoCreateDimensionValues · autoCreatePropertyValues · autoCreateConfig Create missing values or configuration automatically
notifyEmail default, none, or a list of addresses
dataOrigin Label written to the import log
{
  "planId": 3,
  "contentType": "text/csv",
  "fieldMappings": "Department,Month,Value",
  "aggregation": "Sum",
  "autoCreateDimensionValues": false,
  "dataOrigin": "agent: monthly refresh",
  "data": "Department;Month;Amount\n100;202401;1200\n200;202401;800"
}

Semantics are the same as in the GUI and the other transports; see Data integration.

Script validation contract#

validate_script returns a typed result without touching data:

{
  "$type": "Valid",
  "isReadOnly": false,
  "resultSets": [
    {
      "name": "Result",
      "type": "WriteResult",
      "columnNames": ["Inserted", "Updated", "Deleted"],
      "columnTypes": ["…"],
      "writeTarget": { "$type": "…", "valueTypeId": "Amount" }
    }
  ]
}
Field Meaning
$type Valid or Invalid (then error holds the message)
isReadOnly true if the script contains no write statement — safe for execute_read_script
resultSets[].type Query for evaluated expressions, WriteResult for write statements
resultSets[].columnNames · columnTypes Columns of the result set; write results report Inserted, Updated, Deleted
resultSets[].writeTarget Target of a write statement (e.g. valueTypeId)

The write target of a script resolves in the default plan; from plan N in the source query does not change it. use plan N at the start of the script does: see use plan.

Working rules#

The server's own guidance gives agents a small set of working rules: read the tenant instructions first, validate before running, never retry write scripts automatically, read the app-config schema before writing configuration, and respect destructive semantics. They are collected, with known pitfalls per area, in the Agent guide: pitfalls and learnings.

Before any change

Read the Agent guide once. Show the user the validated script or payload and wait for confirmation before calling a write tool.

Kai#

Kai is Konstrukt's in-product assistant, opened from the top bar. It is enabled per tenant with the Kai feature flag and has its own settings page under System (System → Kai); see Tenant administration. The Kex authoring guidelines served to MCP clients are extracted from the practices Kai uses, so scripts written by Kai and by external agents follow the same rules.

AI functionality in the platform is provided through Berget AI, with processing in Sweden. Customer data is not used to train models. See AI and your data ↗ and Hosting and operations.

Beta

Kai is a beta feature under development, so its capabilities are not documented here yet. Usage is shown under System → Kai.

This documentation for agents#

Every page of this site is available as Markdown, and the site publishes an index for language models:

Resource Content
llms.txt Index of all pages with one-line descriptions (llmstxt.org format)
llms-full.txt All pages concatenated as Markdown
md/{slug}.md Markdown source of one page, e.g. md/ai-agents.md

Pages mark agent-specific guidance in For agents callouts.