# 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](security.html#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](security.html#machine-credentials).
4. The client lists the tools and resources the account has access to. Start with `konstrukt://TenantInstructions.md`, see [Working rules](agent-pitfalls.html#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](apis.html).

## 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](kex.html), the Kex reference at [https://acme.konstrukt.app/api/documentation/kex](https://acme.konstrukt.app/api/documentation/kex) (served by every tenant at the same path) and [App configuration](app-config.html).

### 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.

!!! note "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.

!!! note "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 |

```json
{
  "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](integration.html#import-semantics).

## Script validation contract

`validate_script` returns a typed result without touching data:

```json
{
  "$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`](kex.html#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](agent-pitfalls.html#working-rules).

!!! agent "Before any change"
    Read the [Agent guide](agent-pitfalls.html) 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](administration.html). 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 ↗](https://www.konstrukt.se/ai-och-kunddata) and [Hosting and operations](operations.html).

!!! note "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](https://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.

## Related

- [Kex](kex.html)
- [App configuration](app-config.html)
- [Data integration](integration.html)
- [Security and access](security.html)
- [Architecture](architecture.html)
