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.