MCP (Model Context Protocol)¶

C1 Core provides an MCP server that exposes management operations as tools for AI assistants. The server implements the MCP Streamable HTTP transport using JSON-RPC 2.0 over HTTPS.

Endpoint¶

POST https://core.sensaru.net/api/v1/mcp

All MCP communication happens via POST requests to this single endpoint. Each request carries a JSON-RPC 2.0 message in the body.

Authentication¶

MCP uses the same authentication methods as the REST API. See the authentication section for details.

The most common method is API key authentication via the Authorization header:

Authorization: Bearer <your_access_token>

Headers¶

Header	Description
`Authorization`	Bearer token or API key (required)
`Content-Type`	Must be `application/json` (required)
`Mcp-Session-Id`	Session ID returned by `initialize` (required after initialization)
`C1-SYSTEM-PROVIDER`	System provider ID (see below)
`C1-SYSTEM-DISTRIBUTOR`	System distributor ID (see below)
`C1-BUSINESS-PARTNER`	Business partner ID (see below)

Tenant context headers¶

Whether the tenant context headers (C1-SYSTEM-PROVIDER, C1-SYSTEM-DISTRIBUTOR, C1-BUSINESS-PARTNER) are required depends on the user type:

User type	Required headers	Notes
Business partner	None	Context is automatically resolved from the user's identity
System distributor	None	Use the `set_context` tool to set the business partner
System provider	None	Use the `set_context` tool to set the system distributor and business partner
Root	None	Use the `set_context` tool to set all three

The tenant context headers are always accepted and take precedence over the session context. If you prefer to set the context per-request via HTTP headers instead of using the set_context tool, you can do so.

Note

The set_context and get_context tools are only shown to users that need them. Business partner users will not see these tools since their context is always resolved automatically.

ACL¶

MCP access requires the mcp module permission in the user's role. This permission can be configured in the role management UI under module access. The available permission levels are:

Read -- Access to MCP tools (actual data access is governed by the respective module permissions)
Write -- Same as Read (reserved for future use)
Admin -- Same as Write (reserved for future use)

Each tool call is additionally subject to the ACL of the underlying REST endpoint. For example, asset tools require asset-management permission, user management tools require the respective user management permission, etc. A user can only access data they are permitted to see via the REST API.

Protocol¶

Initialize¶

Before using any tools, a client must initialize the session:

curl -X POST https://core.sensaru.net/api/v1/mcp \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-03-26",
      "capabilities": {},
      "clientInfo": {
        "name": "my-client",
        "version": "1.0.0"
      }
    },
    "id": 1
  }'

The response includes an Mcp-Session-Id HTTP header. This session ID must be sent with all subsequent requests:

HTTP/1.1 200 OK
Content-Type: application/json
Mcp-Session-Id: <session_id>

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2025-03-26",
    "capabilities": {
      "tools": {}
    },
    "serverInfo": {
      "name": "c1-core",
      "version": "1.0.0"
    }
  }
}

After initialization, send the notifications/initialized notification (include the Mcp-Session-Id header):

{
  "jsonrpc": "2.0",
  "method": "notifications/initialized",
  "params": {}
}

Sessions expire after 1 hour of inactivity.

List Tools¶

{
  "jsonrpc": "2.0",
  "method": "tools/list",
  "params": {},
  "id": 2
}

Call a Tool¶

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "list_system_providers",
    "arguments": {
      "limit": 10
    }
  },
  "id": 3
}

Available Tools¶

Common list parameters¶

All list tools support the following optional parameters:

Parameter	Type	Description
`search`	string	Full-text search filter
`offset`	string	Pagination cursor (`nextKey` from previous response)
`limit`	integer	Max items to return (default 100, max 10000)
`orderBy`	string	Field to order by
`ascending`	boolean	Sort direction (default `true`)

Asset management¶

list_assets¶

List or search assets with optional filters, pagination, and different output formats.

Parameter	Type	Required	Description
`type`	string	No	Comma-separated asset types: `portfolio`, `economic_unit`, `property`, `administration_unit`
`format`	string	No	Response format: `list` (default), `tree`, `map`, `tree-map`
`portfolioId`	string	No	Filter by portfolio ID
`economicUnitId`	string	No	Filter by economic unit ID
`propertyId`	string	No	Filter by property ID
`administrationUnitId`	string	No	Filter by administration unit ID

Plus common list parameters.

get_asset¶

Get a single asset by ID.

Parameter	Type	Required	Description
`id`	string	Yes	The asset ID (UUID)

create_asset¶

Create a new asset (portfolio, economic unit, property, or administration unit). Additional metadata fields can be passed as extra properties.

Parameter	Type	Required	Description
`locationId`	string	Yes	Location ID in hierarchical format (e.g. `portfolioId` or `portfolioId:economicUnitId`)
`name`	string	Yes	Asset name

update_asset¶

Partially update an asset (PATCH semantics -- only provided fields are changed). Additional metadata fields can be passed as extra properties.

Parameter	Type	Required	Description
`id`	string	Yes	The asset ID (UUID)
`name`	string	No	Updated asset name
`locationId`	string	No	New location ID (moves the asset)

replace_asset¶

Fully replace an asset (PUT semantics -- all fields are replaced). Additional metadata fields can be passed as extra properties.

Parameter	Type	Required	Description
`id`	string	Yes	The asset ID (UUID)
`name`	string	Yes	Asset name
`locationId`	string	Yes	Location ID

delete_asset¶

Delete an asset and update parent child counts.

Parameter	Type	Required	Description
`id`	string	Yes	The asset ID (UUID)

System providers¶

list_system_providers¶

List system providers. Supports common list parameters.

create_system_provider¶

Create a new system provider. Additional metadata fields can be passed as extra properties.

Parameter	Type	Required	Description
`name`	string	Yes	System provider name
`subdomain`	string	Yes	Subdomain
`backgroundColor`	string	Yes	Background color
`color`	string	Yes	Text color
`logo`	string	Yes	Logo (base64 or URL)
`street`	string	No	Street address
`zip`	string	No	ZIP code
`city`	string	No	City
`country`	string	No	Country

get_system_provider¶

Get a single system provider by ID.

Parameter	Type	Required	Description
`id`	string	Yes	System provider ID (UUID)

update_system_provider¶

Update a system provider. Additional metadata fields can be passed as extra properties.

Parameter	Type	Required	Description
`id`	string	Yes	System provider ID (UUID)
`name`	string	No	System provider name
`subdomain`	string	No	Subdomain
`backgroundColor`	string	No	Background color
`color`	string	No	Text color
`logo`	string	No	Logo
`street`	string	No	Street address
`zip`	string	No	ZIP code
`city`	string	No	City
`country`	string	No	Country

delete_system_provider¶

Delete a system provider.

Parameter	Type	Required	Description
`id`	string	Yes	System provider ID (UUID)

list_system_provider_users¶

List users of a system provider. Supports common list parameters.

Parameter	Type	Required	Description
`systemProviderId`	string	Yes	System provider ID (UUID)

create_system_provider_user¶

Create a new user for a system provider. Additional metadata fields can be passed as extra properties.

Parameter	Type	Required	Description
`systemProviderId`	string	Yes	System provider ID (UUID)
`email`	string	Yes	User email address
`locale`	string	Yes	User locale (e.g. en, de)
`firstName`	string	No	First name
`lastName`	string	No	Last name
`groups`	array	No	Array of group IDs

get_system_provider_user¶

Get a single user of a system provider.

Parameter	Type	Required	Description
`systemProviderId`	string	Yes	System provider ID (UUID)
`userId`	string	Yes	User ID (UUID)

update_system_provider_user¶

Update a user of a system provider. Additional metadata fields can be passed as extra properties.

Parameter	Type	Required	Description
`systemProviderId`	string	Yes	System provider ID (UUID)
`userId`	string	Yes	User ID (UUID)
`locale`	string	No	User locale
`firstName`	string	No	First name
`lastName`	string	No	Last name
`groups`	array	No	Array of group IDs

delete_system_provider_user¶

Delete a user of a system provider.

Parameter	Type	Required	Description
`systemProviderId`	string	Yes	System provider ID (UUID)
`userId`	string	Yes	User ID (UUID)

System distributors¶

Same structure as system providers. Tools: list_system_distributors, create_system_distributor, get_system_distributor, update_system_distributor, delete_system_distributor, list_system_distributor_users, create_system_distributor_user, get_system_distributor_user, update_system_distributor_user, delete_system_distributor_user.

The parent ID parameter is systemDistributorId.

Business partners¶

Same structure as system providers, plus one additional tool. Tools: list_business_partners, create_business_partner, get_business_partner, update_business_partner, delete_business_partner, list_business_partner_users, create_business_partner_user, get_business_partner_user, update_business_partner_user, delete_business_partner_user.

The parent ID parameter is businessPartnerId.

create_home_client_default_groups¶

Set the default home client groups for a business partner.

Parameter	Type	Required	Description
`businessPartnerId`	string	Yes	Business partner ID (UUID)
`homeDefaultGroups`	array	Yes	Array of default group IDs

Endusers¶

list_endusers¶

List endusers. Supports common list parameters.

create_enduser¶

Create a new enduser. Additional metadata fields can be passed as extra properties.

Parameter	Type	Required	Description
`email`	string	Yes	Enduser email address
`locale`	string	Yes	Enduser locale (e.g. en, de)
`firstName`	string	No	First name
`lastName`	string	No	Last name
`groups`	array	No	Array of group IDs

get_enduser¶

Get a single enduser by ID.

Parameter	Type	Required	Description
`id`	string	Yes	Enduser ID (UUID)

update_enduser¶

Update an enduser. Additional metadata fields can be passed as extra properties.

Parameter	Type	Required	Description
`id`	string	Yes	Enduser ID (UUID)
`locale`	string	No	Enduser locale
`firstName`	string	No	First name
`lastName`	string	No	Last name
`groups`	array	No	Array of group IDs

delete_enduser¶

Delete an enduser.

Parameter	Type	Required	Description
`id`	string	Yes	Enduser ID (UUID)

User groups¶

Four types of user groups are available, each with the same CRUD operations:

System provider user groups (system_provider_user_groups): list_system_provider_user_groups, create_system_provider_user_group, get_system_provider_user_group, update_system_provider_user_group, delete_system_provider_user_group
System distributor user groups (system_distributor_user_groups): list_system_distributor_user_groups, create_system_distributor_user_group, get_system_distributor_user_group, update_system_distributor_user_group, delete_system_distributor_user_group
Business partner user groups (business_partner_user_groups): list_business_partner_user_groups, create_business_partner_user_group, get_business_partner_user_group, update_business_partner_user_group, delete_business_partner_user_group
Enduser groups (enduser_groups): list_enduser_groups, create_enduser_group, get_enduser_group, update_enduser_group, delete_enduser_group

All list tools support common list parameters.

Create and update parameters:

Parameter	Type	Required (create)	Description
`name`	string	Yes	Group name
`acl`	object	Yes	Access control list configuration

For get, update, and delete: id (string, required) -- the group ID (UUID).

Edge client groups¶

Tools: list_edge_client_groups, create_edge_client_group, get_edge_client_group, update_edge_client_group, delete_edge_client_group.

Same parameters as user groups (name, acl). All list tools support common list parameters.

Building categories¶

list_building_categories¶

List all available building categories (static reference data). This tool takes no parameters.

API keys¶

list_api_keys¶

List API keys for the current user. This tool takes no parameters.

create_api_key¶

Create a new API key for the current user.

Parameter	Type	Required	Description
`name`	string	Yes	API key name

delete_api_key¶

Delete an API key.

Parameter	Type	Required	Description
`id`	string	Yes	API key ID (UUID)

Current user¶

get_current_user¶

Get the current authenticated user's profile. This tool takes no parameters.

update_current_user¶

Partially update the current user's profile. Additional metadata fields can be passed as extra properties.

Parameter	Type	Required	Description
`locale`	string	No	User locale
`firstName`	string	No	First name
`lastName`	string	No	Last name

replace_current_user¶

Fully replace the current user's profile. Additional metadata fields can be passed as extra properties.

Parameter	Type	Required	Description
`locale`	string	No	User locale
`firstName`	string	No	First name
`lastName`	string	No	Last name

delete_current_user¶

Delete the current user's account. This tool takes no parameters.

Tenant context¶

set_context¶

Set the tenant context for the current session. This tool is only available to root, system provider, and system distributor users. Each entity can be specified by UUID or by name (or part of the name). If a name matches multiple entries, the matching options are returned.

When a business partner is specified, the system distributor and system provider are automatically resolved from the hierarchy.

The available parameters depend on the user type:

User type	Available parameters
Root	`systemProviderId` / `systemProviderName`, `systemDistributorId` / `systemDistributorName`, `businessPartnerId` / `businessPartnerName`
System provider	`systemDistributorId` / `systemDistributorName`, `businessPartnerId` / `businessPartnerName`
System distributor	`businessPartnerId` / `businessPartnerName`

Parameter	Type	Required	Description
`systemProviderId`	string	No	System provider UUID (root users only)
`systemProviderName`	string	No	System provider name or partial name (root users only)
`systemDistributorId`	string	No	System distributor UUID
`systemDistributorName`	string	No	System distributor name or partial name
`businessPartnerId`	string	No	Business partner UUID
`businessPartnerName`	string	No	Business partner name or partial name

The context persists for the session and can be changed at any time by calling set_context again. The response returns the effective context after validation.

Example (setting context by name):

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "set_context",
    "arguments": {
      "businessPartnerName": "Hausverwaltung Müller"
    }
  },
  "id": 3
}

Example (setting context by UUID):

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "set_context",
    "arguments": {
      "systemDistributorId": "<sd_uuid>",
      "businessPartnerId": "<bp_uuid>"
    }
  },
  "id": 3
}

get_context¶

Get the current effective tenant context for the session. Returns the system provider, system distributor, and business partner IDs. This tool is only available to root, system provider, and system distributor users.

This tool takes no parameters.

Device management¶

Device management tools are provided by the c1-device-management module. They manage IoT devices, data points, commissioning cards, service messages, and dashboards. All tool names are prefixed with dm_.

Note

Device management tools operate within the current business partner context. System provider and system distributor users must set the business partner context first using the set_context tool.

dm_list_devices¶

List all devices for the current business partner with optional filtering, search, and pagination.

Parameter	Type	Required	Description
`lang`	string	No	Language code (e.g. en-US)
`search`	string	No	Full-text search filter
`locationId`	string	No	Filter by asset/location UUID
`locationIdFilterType`	string	No	Location filter mode: `parent` (include children) or `exact`
`roles`	string	No	Comma-separated role IDs to filter by
`tags`	string	No	Comma-separated tags to filter by
`deviceType`	string	No	Filter by device type
`operationMode`	string	No	Filter by operation mode
`filter`	string	No	Additional filter (e.g. `unconfigured`)
`virtualDevices`	string	No	Include virtual devices (`true` or `false`)
`groupBy`	string	No	Group results by field (e.g. `locationId`)
`configFields`	string	No	Include configuration fields (`true` or `false`)
`orderBy`	string	No	Field to order by (default: `id`)
`ascending`	string	No	Sort ascending (`true` or `false`)
`offset`	string	No	Pagination cursor
`limit`	integer	No	Max results (default 100, max 1000)

dm_create_device¶

Create a new device. Additional metadata fields can be passed as extra properties.

Parameter	Type	Required	Description
`serialNumber`	string	Yes	Device serial number
`name`	string	No	Device name
`notes`	string	No	Device notes
`setupKey`	string	No	Setup key
`locationId`	string	No	Asset/location UUID to assign to
`lang`	string	No	Language code (e.g. en-US)

dm_get_device¶

Get details of a specific device.

Parameter	Type	Required	Description
`deviceId`	string	Yes	Device ID (UUID)
`lang`	string	No	Language code (e.g. en-US)
`configFields`	string	No	Include configuration fields (`true` or `false`)

dm_update_device¶

Partially update a device (merge update). Additional metadata fields can be passed as extra properties.

Parameter	Type	Required	Description
`deviceId`	string	Yes	Device ID (UUID)
`name`	string	No	Device name
`notes`	string	No	Device notes
`locationId`	string	No	Asset/location UUID
`operationMode`	string	No	Operation mode

dm_replace_device¶

Replace/fully update a device. Additional metadata fields can be passed as extra properties.

Parameter	Type	Required	Description
`deviceId`	string	Yes	Device ID (UUID)
`name`	string	No	Device name
`notes`	string	No	Device notes
`locationId`	string	No	Asset/location UUID
`operationMode`	string	No	Operation mode

dm_delete_device¶

Delete a device.

Parameter	Type	Required	Description
`deviceId`	string	Yes	Device ID (UUID)
`lang`	string	No	Language code (e.g. en-US)

dm_get_device_statistics¶

Get device statistics for the current business partner.

Parameter	Type	Required	Description
`lang`	string	No	Language code (e.g. en-US)

dm_assign_device¶

Assign a gateway to device(s) using serial number and setup key.

Parameter	Type	Required	Description
`serialNumber`	string	Yes	Gateway serial number
`setupKey`	string	Yes	Setup key
`name`	string	No	Device/gateway name
`notes`	string	No	Notes
`lang`	string	No	Language code (e.g. en-US)

dm_requeue_packets¶

Requeue packets for a device. Additional metadata fields can be passed as extra properties.

Parameter	Type	Required	Description
`deviceId`	string	Yes	Device ID (UUID)

dm_set_sensor_data¶

Set sensor data for a device. Additional metadata fields can be passed as extra properties.

Parameter	Type	Required	Description
`deviceId`	string	Yes	Device ID (UUID)

Data points¶

dm_list_all_data_points¶

List data points across all devices, filtered by roles and optionally by location.

Parameter	Type	Required	Description
`roles`	string	Yes	Comma-separated role IDs
`locationId`	string	No	Filter by asset/location UUID
`locationIdFilterType`	string	No	Location filter mode: `parent` or `exact`
`virtualDevices`	string	No	Include virtual devices (`true` or `false`)
`lang`	string	No	Language code
`orderBy`	string	No	Field to order by (default: `id`)
`ascending`	string	No	Sort ascending (`true` or `false`)
`offset`	string	No	Pagination cursor
`limit`	integer	No	Max results (default 100, max 1000)

dm_list_device_data_points¶

List all data points for a specific device.

Parameter	Type	Required	Description
`deviceId`	string	Yes	Device ID (UUID)
`lang`	string	No	Language code
`orderBy`	string	No	Field to order by (default: `id`)
`ascending`	string	No	Sort ascending (`true` or `false`)
`offset`	string	No	Pagination cursor
`limit`	integer	No	Max results (default 100, max 1000)

dm_get_data_point¶

Get details of a specific data point.

Parameter	Type	Required	Description
`deviceId`	string	Yes	Device ID (UUID)
`dataPointId`	string	Yes	Data point ID
`lang`	string	No	Language code

dm_update_data_point¶

Partially update data point metadata (merge update). Additional metadata fields can be passed as extra properties.

Parameter	Type	Required	Description
`deviceId`	string	Yes	Device ID (UUID)
`dataPointId`	string	Yes	Data point ID

dm_replace_data_point¶

Replace data point metadata completely. Additional metadata fields can be passed as extra properties.

Parameter	Type	Required	Description
`deviceId`	string	Yes	Device ID (UUID)
`dataPointId`	string	Yes	Data point ID

dm_get_data_point_log¶

Get log entries for a specific data point with optional time range, aggregation, and formatting.

Parameter	Type	Required	Description
`deviceId`	string	Yes	Device ID (UUID)
`dataPointId`	string	Yes	Data point ID
`dateFrom`	string	No	Start time (unix timestamp in seconds)
`dateTo`	string	No	End time (unix timestamp in seconds)
`timeFormat`	string	No	Time format: `unix-timestamp-seconds`, `unix-timestamp-milliseconds`, or `iso-8601`
`dataPointFormat`	string	No	Data point format: `raw` or `localized`
`convertToNumber`	string	No	Convert values to numbers (`true` or `false`)
`aggregate`	string	No	Aggregation: `none`, `15m`, `hour`, `day`, or `all`
`ascending`	string	No	Sort ascending (`true` or `false`)
`offset`	string	No	Pagination cursor
`limit`	integer	No	Max results (default 100, max 10000)
`lang`	string	No	Language code

dm_create_data_point_log¶

Create log entries for a data point. Body is an array of [timestamp, value] pairs. Additional metadata fields can be passed as extra properties.

Parameter	Type	Required	Description
`deviceId`	string	Yes	Device ID (UUID)
`dataPointId`	string	Yes	Data point ID

dm_delete_data_point_log_entry¶

Delete a specific log entry by local and UTC timestamps.

Parameter	Type	Required	Description
`deviceId`	string	Yes	Device ID (UUID)
`dataPointId`	string	Yes	Data point ID
`localTime`	string	Yes	Local timestamp in milliseconds
`utcTime`	string	Yes	UTC timestamp in milliseconds

dm_list_logs¶

Get data point logs across devices, filtered by roles and optionally by location.

Parameter	Type	Required	Description
`roles`	string	Yes	Comma-separated role IDs
`locationId`	string	No	Filter by asset/location UUID
`locationIdFilterType`	string	No	Location filter mode: `parent` or `exact`
`dateFrom`	string	No	Start time (unix timestamp in seconds)
`dateTo`	string	No	End time (unix timestamp in seconds)
`timeFormat`	string	No	Time format: `unix-timestamp-seconds`, `unix-timestamp-milliseconds`, or `iso-8601`
`dataPointFormat`	string	No	Data point format: `raw` or `localized`
`convertToNumber`	string	No	Convert values to numbers (`true` or `false`)
`aggregate`	string	No	Aggregation: `hour`, `day`, `year`, or `all`
`virtualDevices`	string	No	Include virtual devices (`true` or `false`)
`offset`	string	No	Pagination cursor
`limit`	integer	No	Max results (default 100, max 10000)
`lang`	string	No	Language code

dm_list_energy_data¶

Get energy consumption data, optionally filtered by location.

Parameter	Type	Required	Description
`locationId`	string	No	Filter by asset/location UUID
`locationIdFilterType`	string	No	Location filter mode: `parent` or `exact`
`dateFrom`	string	No	Start time (unix timestamp in seconds)
`dateTo`	string	No	End time (unix timestamp in seconds)
`dataPointFormat`	string	No	Data point format: `raw` or `localized`
`offset`	string	No	Pagination cursor
`limit`	integer	No	Max results (default 100, max 10000)
`lang`	string	No	Language code

Commissioning cards¶

dm_list_commissioning_cards¶

List commissioning cards for the current business partner.

Parameter	Type	Required	Description
`offset`	string	No	Pagination cursor
`limit`	integer	No	Max results (default 100, max 1000)

dm_create_commissioning_card¶

Create a new commissioning card.

Parameter	Type	Required	Description
`serialNumber`	string	Yes	Serial number (will be uppercased)
`name`	string	Yes	Card name

dm_get_commissioning_card¶

Get a specific commissioning card by serial number.

Parameter	Type	Required	Description
`cardId`	string	Yes	Commissioning card serial number

dm_update_commissioning_card¶

Update a commissioning card (name only).

Parameter	Type	Required	Description
`cardId`	string	Yes	Commissioning card serial number
`name`	string	No	New card name

dm_replace_commissioning_card¶

Replace a commissioning card.

Parameter	Type	Required	Description
`cardId`	string	Yes	Commissioning card serial number
`name`	string	No	New card name

dm_delete_commissioning_card¶

Delete a commissioning card.

Parameter	Type	Required	Description
`cardId`	string	Yes	Commissioning card serial number

Service messages¶

dm_list_service_messages¶

List service messages with optional filtering by location, roles, status, and search.

Parameter	Type	Required	Description
`locationId`	string	No	Filter by asset/location UUID
`locationIdFilterType`	string	No	Location filter mode: `parent` or `exact`
`roles`	string	No	Comma-separated role IDs
`filter`	string	No	Comma-separated status filters
`search`	string	No	Search text
`lang`	string	No	Language code
`offset`	string	No	Pagination cursor
`limit`	integer	No	Max results (default 100, max 1000)

dm_get_service_message¶

Get a specific service message.

Parameter	Type	Required	Description
`messageId`	string	Yes	Service message ID
`lang`	string	No	Language code

dm_list_device_service_messages¶

List service messages for a specific device.

Parameter	Type	Required	Description
`deviceId`	string	Yes	Device ID (UUID)
`locationId`	string	No	Filter by asset/location UUID
`locationIdFilterType`	string	No	Location filter mode: `parent` or `exact`
`roles`	string	No	Comma-separated role IDs
`filter`	string	No	Comma-separated status filters
`search`	string	No	Search text
`lang`	string	No	Language code
`offset`	string	No	Pagination cursor
`limit`	integer	No	Max results (default 100, max 1000)

Dashboards¶

dm_get_app_dashboard¶

Get application dashboard data.

Parameter	Type	Required	Description
`locationId`	string	Yes	Asset/location UUID
`lang`	string	No	Language code (default: en-US)
`year`	integer	No	Year for time-based data
`month`	integer	No	Month (requires year)
`day`	integer	No	Day (requires year and month)

dm_get_business_ui_dashboard¶

Get business UI dashboard data.

Parameter	Type	Required	Description
`locationId`	string	Yes	Asset/location UUID
`lang`	string	No	Language code (default: en-US)
`year`	integer	No	Year for time-based data
`month`	integer	No	Month (requires year)
`day`	integer	No	Day (requires year and month)

dm_get_energy_dashboard¶

Get energy dashboard data.

Parameter	Type	Required	Description
`locationId`	string	Yes	Asset/location UUID
`lang`	string	No	Language code (default: en-US)
`year`	integer	No	Year for time-based data
`month`	integer	No	Month (requires year)
`day`	integer	No	Day (requires year and month)

dm_get_main_dashboard¶

Get main dashboard data.

Parameter	Type	Required	Description
`locationId`	string	No	Asset/location UUID
`lang`	string	No	Language code (default: en-US)

dm_get_optimizer_dashboard¶

Get optimizer dashboard data.

Parameter	Type	Required	Description
`locationId`	string	No	Asset/location UUID
`lang`	string	No	Language code (default: en-US)

Optimizer status¶

dm_get_optimizer_status¶

Check optimizer dashboard readiness for an economic unit. Returns the status of optimizer devices, property data completeness, and consumption settings. The response includes assetId for each section so the AI knows exactly which asset to update.

Parameter	Type	Required	Description
`locationId`	string	Yes	Asset/location UUID at economic unit level or below

Response structure:

{
  "ready": false,
  "isMultiProperty": true,
  "optimizerDevices": {
    "found": true,
    "count": 2,
    "allConfigured": true,
    "unconfiguredDevices": []
  },
  "propertyData": {
    "complete": false,
    "incompleteProperties": [
      {"assetId": "...", "name": "Musterstr. 5", "missingFields": ["numberOfResidentialUnits"]}
    ]
  },
  "consumptionSettings": [
    {
      "assetId": "...",
      "name": "Musterstr. 5",
      "set": false,
      "previousYearConsumption": null,
      "pricePerKwh": 0.10,
      "hasCentralHotWater": true,
      "hotWaterDeductionMode": "calculate"
    }
  ]
}

How to fix issues:

Missing consumption settings: Call update_asset with the assetId from consumptionSettings. Fields: previousYearConsumption (kWh), previousYearConsumptionRaw (kWh, before hot water deduction), pricePerKwh (EUR), hotWaterDeductionMode (calculate or manual), hotWaterManualDeduction (kWh).
Incomplete property data: Call update_asset with the assetId from propertyData.incompleteProperties. Set the fields listed in missingFields: yearOfConstruction, numberOfFloors, livingArea (m²), numberOfResidentialUnits.
Multi-property mode: Consumption settings are stored on each property asset that has an optimizer.
Single-property mode: Consumption settings are stored on the economic unit asset.

Gateways (system provider only)¶

dm_list_gateways¶

List all gateways. This tool requires system provider access and a business partner context of 0.

Parameter	Type	Required	Description
`search`	string	No	Search text
`bp_ids`	string	No	Comma-separated business partner UUIDs
`limit`	integer	No	Max results (default 50, max 1000)
`offset`	string	No	Pagination offset

Device inbox (system provider only)¶

dm_list_device_inbox¶

List unassigned devices in the inbox. This tool requires system provider access and a business partner context of 0.

Parameter	Type	Required	Description
`search`	string	No	Search text
`limit`	integer	No	Max results (default 50, max 1000)
`offset`	string	No	Pagination offset

Roles (reference data)¶

dm_list_roles¶

List available device data point roles. Returns role IDs, translated names, and default aggregation methods. Use numericId values when filtering data points by role (e.g. in dm_list_all_data_points).

Parameter	Type	Required	Description
`search`	string	No	Search filter (matches role ID and translated names, case-insensitive)
`lang`	string	No	Language code for role names (e.g. `en-US`, `de-DE`). Default: `en-US`

Example response entry:

{
  "id": "20.10.15",
  "numericId": 201015,
  "name": "heating system - current heating power",
  "aggregation": "max"
}

Device types (reference data)¶

dm_list_device_types¶

List all known device type descriptions. Returns type IDs, names, roles, and sections for each device type.

This tool takes no parameters.

dm_get_device_type¶

Get the full description of a specific device type, including all data points with their native IDs, types, units, aggregation methods, and intervals.

Parameter	Type	Required	Description
`typeId`	string	Yes	Device type identifier (e.g. `s1-02-01`, `v1-06-01`, `g1`)

Service message management (c1-service-messages)¶

The following tools are provided by the c1-service-messages module. They manage service messages (alarms), alarm definitions, alarm chains (notification routing), and notifications.

sm_list_service_messages¶

List active service messages (alarms) for the current business partner. Priorities: critical, error, warning, info, offline.

Parameter	Type	Required	Description
`lang`	string	No	Language code for translated headers/messages (e.g. `en-US`, `de-DE`)
`locationId`	string	No	Filter by asset/location ID
`locationIdFilterType`	string	No	Location filter mode: `parent` (include children) or `exact`
`filter`	string	No	Comma-separated priority filter (e.g. `critical,error,warning`)
`search`	string	No	Full-text search filter
`limit`	integer	No	Max results (default 100, max 1000)
`offset`	string	No	Pagination cursor (from `responseMetadata.nextKey`)

sm_get_service_message_logs¶

Get the state change log for a specific service message. States: 0=triggered, 1=assigned, 2=resolved.

Parameter	Type	Required	Description
`messageId`	string	Yes	Service message ID
`limit`	integer	No	Max results (default 100, max 1000)

sm_get_service_messages_report¶

Generate an alarm report with aggregated statistics for a location and time range. Requires unrestricted access.

Parameter	Type	Required	Description
`locationId`	string	No	Asset/location ID to report on
`dateFrom`	integer	No	Start date as Unix epoch in seconds
`dateTo`	integer	No	End date as Unix epoch in seconds

sm_list_alarm_definitions¶

List all alarm definitions (custom alarm rules). Alarm definitions link alarm templates to specific devices or locations. Requires unrestricted access.

Parameter	Type	Required	Description
`locationId`	string	No	Filter by asset/location ID
`locationIdFilterType`	string	No	Location filter mode: `parent` or `exact`

sm_get_alarm_definition¶

Get details of a specific alarm definition. Requires unrestricted access.

Parameter	Type	Required	Description
`definitionId`	string	Yes	Alarm definition ID

sm_create_alarm_definition¶

Create a new alarm definition. Links an alarm template to a location and optionally a device. Use sm_list_alarm_definition_templates to find available templates. Requires unrestricted access.

Parameter	Type	Required	Description
`locationId`	string	Yes	Asset/location ID where the alarm applies
`priority`	integer	Yes	Alarm priority 1-5 (1=info, 2=warning, 3=error, 4=critical, 5=offline)
`alarmDefinitionTemplateId`	string	Yes	ID of the alarm template to use
`deviceId`	string	No	Device ID to attach the alarm to
`values`	object	No	Template-specific configuration values (e.g. thresholds)

sm_update_alarm_definition¶

Update an existing alarm definition. All fields are replaced. Requires unrestricted access.

Parameter	Type	Required	Description
`definitionId`	string	Yes	Alarm definition ID
`locationId`	string	Yes	Asset/location ID
`priority`	integer	Yes	Alarm priority 1-5
`alarmDefinitionTemplateId`	string	No	ID of the alarm template
`deviceId`	string	No	Device ID to attach the alarm to
`values`	object	No	Template-specific configuration values

sm_delete_alarm_definition¶

Delete an alarm definition. Also removes the alarm from the associated device if any. Requires unrestricted access.

Parameter	Type	Required	Description
`definitionId`	string	Yes	Alarm definition ID

sm_list_alarm_chains¶

List all alarm chains (notification routing rules). Alarm chains define who gets notified when service messages of certain priorities are triggered. Requires unrestricted access.

Parameter	Type	Required	Description
`orderBy`	string	No	Field to order by (default: `id`)
`ascending`	string	No	Sort ascending (`true` or `false`, default: `true`)
`locationId`	string	No	Filter by asset/location ID
`locationIdFilterType`	string	No	Location filter mode: `parent` or `exact`
`search`	string	No	Full-text search filter
`limit`	integer	No	Max results (default 100, max 1000)
`offset`	string	No	Pagination cursor

sm_get_alarm_chain¶

Get details of a specific alarm chain including its observers, service users, schedule, and active service messages. Requires unrestricted access.

Parameter	Type	Required	Description
`chainId`	string	Yes	Alarm chain ID

sm_create_alarm_chain¶

Create a new alarm chain (notification routing rule). Requires unrestricted access.

Parameter	Type	Required	Description
`name`	string	Yes	Name of the alarm chain
`priorities`	array	Yes	Priority strings that trigger this chain (e.g. `["critical", "error"]`)
`settings`	object	No	Alarm chain settings (notification intervals)
`alarmSchedule`	array	No	Escalation schedule defining notification timing
`observers`	array	No	Observer objects who receive notifications
`serviceUsers`	array	No	Service user objects who can be assigned to alarms
`locationIdsExact`	array	No	Exact location IDs this chain covers
`locationIdsParent`	array	No	Parent location IDs (includes children)
`locationIdsJson`	object	No	Structured location ID configuration
`roleIds`	array	No	Numeric role IDs this chain covers
`roleIdsJson`	object	No	Structured role ID configuration
`emailText`	object	No	Custom email notification text template
`smsText`	object	No	Custom SMS notification text template

sm_update_alarm_chain¶

Update an existing alarm chain. All fields are replaced. Requires unrestricted access.

Parameter	Type	Required	Description
`chainId`	string	Yes	Alarm chain ID
`name`	string	No	Name of the alarm chain
`priorities`	array	No	Priority strings (e.g. `["critical", "error"]`)
`settings`	object	No	Alarm chain settings
`alarmSchedule`	array	No	Escalation schedule
`observers`	array	No	Observer objects
`serviceUsers`	array	No	Service user objects
`locationIdsExact`	array	No	Exact location IDs
`locationIdsParent`	array	No	Parent location IDs
`locationIdsJson`	object	No	Structured location ID configuration
`roleIds`	array	No	Numeric role IDs
`roleIdsJson`	object	No	Structured role ID configuration
`emailText`	object	No	Custom email notification text
`smsText`	object	No	Custom SMS notification text

sm_delete_alarm_chain¶

Delete an alarm chain. Requires unrestricted access.

Parameter	Type	Required	Description
`chainId`	string	Yes	Alarm chain ID

sm_list_alarm_chain_notifications¶

List notification log entries for a specific alarm chain. Shows which notifications were sent and their delivery status. Requires unrestricted access.

Parameter	Type	Required	Description
`chainId`	string	Yes	Alarm chain ID
`limit`	integer	No	Max results (default 100, max 1000)
`search`	string	No	Search filter
`offset`	string	No	Pagination offset

sm_get_alarm_chain_notification¶

Get details of a specific notification sent by an alarm chain. Requires unrestricted access.

Parameter	Type	Required	Description
`chainId`	string	Yes	Alarm chain ID
`messageId`	string	Yes	Notification message ID

sm_list_notifications¶

List all notification log entries across all alarm chains. Requires unrestricted access.

Parameter	Type	Required	Description
`locationId`	string	No	Filter by asset/location ID
`locationIdFilterType`	string	No	Location filter mode: `parent` or `exact`
`limit`	integer	No	Max results (default 100, max 1000)
`search`	string	No	Search filter
`offset`	string	No	Pagination offset

sm_get_notification¶

Get details of a specific notification message. Requires unrestricted access.

Parameter	Type	Required	Description
`messageId`	string	Yes	Notification message ID

sm_list_alarm_definition_templates¶

List all available alarm definition templates. Templates define the types of alarms that can be configured (e.g. temperature threshold, device offline). Use the template IDs when creating alarm definitions with sm_create_alarm_definition.

Parameter	Type	Required	Description
`lang`	string	No	Language code for translated labels (e.g. `en-US`, `de-DE`)

Tool Response Format¶

Tool results follow the MCP content format:

Success:

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"systemProviders\": [...], \"nextKey\": \"...\"}"
      }
    ]
  }
}

Error:

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "isError": true,
    "content": [
      {
        "type": "text",
        "text": "Error: Unauthorized."
      }
    ]
  }
}

Error Codes¶

MCP uses standard JSON-RPC 2.0 error codes:

Code	Meaning
-32700	Parse error (invalid JSON)
-32600	Invalid request (missing or wrong `jsonrpc` version)
-32601	Method not found
-32602	Invalid params (missing required tool parameter)
-32603	Internal error