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