> For the complete documentation index, see [llms.txt](https://docs.widgelix.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.widgelix.com/ai-integration-mcp-server/introduction.md).

# Introduction

## Widgelix MCP Connector

Connect Claude (and any MCP-compatible AI client) to your Widgelix IoT platform. The connector exposes 27 tools covering the full platform surface — devices, telemetry, rules, dashboards, device types, and events — letting you query, analyze, and manage your IoT fleet through natural language.

***

### Connection

**MCP Server URL:** `https://mcp.widgelix.com`

Add this URL to your MCP client (Claude Desktop, Claude.ai Connectors, custom client). Authentication is handled at the server level using your Widgelix account credentials.

***

### Multi-Organization Support

All tools accept an optional `organizationId` parameter. Omit it when your account belongs to a single organization. Pass the ID explicitly when your account has access to multiple organizations.

***

### Tools Reference

#### Devices

| Tool                             | Description                                                                                                                                     |
| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `list_devices_with_device_types` | Returns all devices in the fleet together with their device type metadata in a single call. Preferred starting point for any fleet exploration. |
| `get_last_device_payload`        | Returns the most recent raw telemetry payload received from a device.                                                                           |
| `get_device_telemetry`           | Returns historical telemetry for one or more fields on a device, with optional aggregation.                                                     |
| `get_device_events`              | Returns event log for a specific device over a time range.                                                                                      |
| `get_organization_events`        | Returns events across all (or selected) devices in the organization for a time range.                                                           |

**`get_device_telemetry` parameters**

| Parameter         | Type           | Notes                                                                                                 |
| ----------------- | -------------- | ----------------------------------------------------------------------------------------------------- |
| `deviceName`      | string         | Device ID or name from `list_devices_with_device_types`                                               |
| `fields`          | string\[]      | Field names from the device type's `uplinkConverter.dataFields`                                       |
| `lastFrom`        | string \| null | Relative range: `"1 hour"`, `"1 day"`, `"1 week"`, `"1 month"`. Set to `null` when using `min`/`max`. |
| `min`             | number \| null | Unix timestamp in ms (start). Use with `max` instead of `lastFrom`.                                   |
| `max`             | number \| null | Unix timestamp in ms (end).                                                                           |
| `aggregation`     | boolean        | Enable time-bucket aggregation                                                                        |
| `aggregationType` | string         | `min` \| `max` \| `avg` \| `sum` \| `diff`                                                            |
| `resolution`      | string         | `5 minutes` \| `10 minutes` \| `30 minutes` \| `1 hour` \| `1 day` \| `1 week`                        |
| `organizationId`  | string         | Optional                                                                                              |

> **Note:** `lastFrom` and `min`/`max` are mutually exclusive. Use one or the other.

***

#### Device Types

| Tool                   | Description                                                                                                                                     |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `get_device_type`      | Returns full device type metadata including the `uplinkConverter.dataFields` array — the canonical list of telemetry field names for that type. |
| `get_device_type_tags` | Returns the tag set used in rule message placeholders (`[[Operated_Device.TAG]]`).                                                              |
| `update_device_type`   | Updates an existing device type. Requires the full device type object plus its ID.                                                              |
| `create_device_type`   | Creates a new device type. Read `widgelix://docs/device-types/schema` before calling.                                                           |
| `check_uplink_code`    | Validates an uplink decoder against a sample HEX payload before applying it.                                                                    |
| `check_downlink_code`  | Validates a downlink encoder against a sample payload.                                                                                          |

> When looking up device type IDs, always use `deviceTypes[].id` from `list_devices_with_device_types`, not the name or slug.

***

#### Rules

| Tool               | Description                                                                                                             |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------- |
| `list_rules`       | Returns all rules: ID, name, type, enabled state, actions, last executed.                                               |
| `get_rule`         | Returns the full rule definition including statements and actions.                                                      |
| `create_rule`      | Creates a new rule. Read `widgelix://docs/rules/schema` first.                                                          |
| `update_rule`      | Updates an existing rule. The rule object must include its `id`.                                                        |
| `set_rule_enabled` | Enables or disables a rule by ID.                                                                                       |
| `get_rule_schema`  | Shortcut that returns the rule JSON Schema + example + placeholder documentation in one call. Use before `create_rule`. |

**Rule types**

| Value     | Severity       |
| --------- | -------------- |
| `Info`    | Informational  |
| `Warning` | Warning        |
| `Danger`  | Critical alert |

**Required rule fields**

`name`, `type`, `customMessage`, `offlineAlert`, `passPayload`, `isEnabled`, `triggerOnce`, `anyDay`, `schedule`, `statements`, `actions`

**Message placeholders**

Use `get_device_type_tags` to discover available tags, then reference them in rule messages as `[[Operated_Device.TAG_NAME]]`.

***

#### Dashboards

| Tool                   | Description                                                                                                                             |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `list_dashboards`      | Returns all global dashboards: ID, name, icon, description.                                                                             |
| `get_dashboard`        | Returns full dashboard definition including live widget data.                                                                           |
| `create_dashboard`     | Creates a new global dashboard.                                                                                                         |
| `update_dashboard`     | Updates an existing dashboard. The dashboard object must include its `id`.                                                              |
| `get_dashboard_schema` | Shortcut that returns the dashboard JSON Schema + widget reference + layout rules + example in one call. Use before `create_dashboard`. |

***

#### Documentation

| Tool                 | Description                             |
| -------------------- | --------------------------------------- |
| `list_documentation` | Lists all available documentation URIs. |
| `get_documentation`  | Fetches documentation content by URI.   |

**Available documentation URIs**

| URI                                    | Contents                |
| -------------------------------------- | ----------------------- |
| `widgelix://docs/overview`             | Platform overview       |
| `widgelix://docs/rules/schema`         | Rule JSON Schema        |
| `widgelix://docs/rules/example`        | Rule example payload    |
| `widgelix://docs/rules/placeholders`   | Placeholder reference   |
| `widgelix://docs/dashboards/schema`    | Dashboard JSON Schema   |
| `widgelix://docs/dashboards/widgets`   | Widget type reference   |
| `widgelix://docs/dashboards/layout`    | Layout rules            |
| `widgelix://docs/dashboards/example`   | Dashboard example       |
| `widgelix://docs/devices/schema`       | Device schema           |
| `widgelix://docs/device-types/schema`  | Device type JSON Schema |
| `widgelix://docs/device-types/example` | Device type example     |
| `widgelix://docs/device-types/decoder` | Decoder guide           |
| `widgelix://docs/events/schema`        | Event schema            |

***

#### Utility

| Tool   | Description                     |
| ------ | ------------------------------- |
| `ping` | Checks MCP server availability. |

***

### Recommended Workflows

#### Explore the fleet

```
1. list_devices_with_device_types
   → gets all devices + device type metadata in one call

2. get_last_device_payload(deviceName)
   → inspect the raw payload structure

3. get_device_telemetry(deviceName, fields, lastFrom="1 day")
   → query historical data for specific fields
```

#### Analyze device data

```
1. list_devices_with_device_types
   → find device ID and field names from deviceTypes[].uplinkConverter.dataFields

2. get_device_telemetry(deviceName, fields, aggregation=true, aggregationType="avg", resolution="1 hour", lastFrom="1 week")
   → get hourly averages over the past week

3. get_device_events(deviceName, lastFrom="1 week")
   → correlate anomalies with rule-triggered events
```

#### Create or update a rule

```
1. get_rule_schema
   → read the full schema, example, and placeholder docs

2. list_devices_with_device_types
   → find the device type ID you want to target

3. get_device_type_tags(deviceTypeId)
   → discover available [[Operated_Device.TAG]] placeholders

4. create_rule(rule)   or   get_rule(ruleId) → edit → update_rule(rule)

5. set_rule_enabled(ruleId, isEnabled=true)
```

#### Build or update a dashboard

```
1. get_dashboard_schema
   → read schema, widget reference, layout rules, and example

2. list_dashboards
   → find an existing dashboard to use as template (optional)

3. get_dashboard(dashboardId)
   → copy the full structure as a starting point (optional)

4. create_dashboard(dashboard)   or   update_dashboard(dashboard)
```

#### Audit organization-wide events

```
1. get_organization_events(deviceIds=[], lastFrom="1 week")
   → returns all rule-triggered events across the fleet

2. get_device_events(deviceName, lastFrom="1 day", count=50)
   → drill into a specific device
```

***

### Best Practices

**Always look up IDs before referencing them.** Use `list_*` tools to get IDs, then pass those IDs to `get_*`, `update_*`, and `create_*` tools. Names and slugs are accepted as fallbacks only.

**Discover field names before querying telemetry.** Call `list_devices_with_device_types` and read `deviceTypes[].uplinkConverter.dataFields` to get the exact field names expected by `get_device_telemetry`.

**Read the schema before creating objects.** Call `get_rule_schema` before `create_rule`, and `get_dashboard_schema` before `create_dashboard`. These shortcut tools return everything you need in a single call.

**Validate decoders before deploying.** Use `check_uplink_code` and `check_downlink_code` to test converter logic against sample payloads before writing it to a device type.

**Use `lastFrom` for convenience, `min`/`max` for precision.** The two modes are mutually exclusive — use one or the other in a single request.

***

### Time Range Reference

| `lastFrom` value | Period          |
| ---------------- | --------------- |
| `"1 hour"`       | Last 60 minutes |
| `"1 day"`        | Last 24 hours   |
| `"1 week"`       | Last 7 days     |
| `"1 month"`      | Last 30 days    |

For absolute ranges, pass Unix timestamps in milliseconds to `min` and `max`, and set `lastFrom` to `null`.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.widgelix.com/ai-integration-mcp-server/introduction.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.