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#
- In the MCP client, add a remote MCP server (connector) with the URL
https://{tenant}.konstrukt.app/api/mcp. - Connect. The client opens a Konstrukt sign-in page in the browser.
- Sign in with an API key: enter the Key ID as client ID and the API key as client secret. See Machine credentials.
- 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 area-z A-Z 0-9 . - _ ~and/. Documents appear askonstrukt://tenant/{name}.- Saving
TenantInstructions.mdrewrites the tenant instructions sent to clients. It cannot be deleted; save empty content to stop sending instructions. delete_mcp_resourcedeletes a document permanently.- A proven pattern: one document per plan under
plans/, each linked fromTenantInstructions.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.