These are the tools an AI agent gets when you connect it to Thinger.io through the MCP server, and the resource types it can work with. The agent uses them with the permissions of your token: see Permissions. The lists on this page are generated from the MCP server itself.
Today you connect through the CLI
The MCP server runs with the thinger CLI (thinger mcp), as Connect an AI agent explains. The tools on this page are the ones of the CLI version below.
| Package | Version |
|---|---|
@thinger-io/cli | 0.5.1 |
@thinger-io/cli-core | 0.5.2 |
Tools
| Tool | Description | Read-only mode |
|---|---|---|
thinger_resource_describe | Describes a resource type. | Yes |
thinger_resource_list | Lists the records of a type, one JSON record per line with the ids to pass back, a page at a time. | Yes |
thinger_resource_get | Reads one record as JSON, located by ids. | Yes |
thinger_resource_create | Creates a record from body, with the fields thinger_resource_describe shows. | |
thinger_resource_update | Updates a resource with the fields in body and keeps the fields you leave out. | |
thinger_resource_delete | Deletes the record ids locates, or the file of a storage_file. | |
thinger_resource_clone | Copies the record ids locates under a new ID. | |
thinger_resource_call | Runs an action of a resource that is not create, read, update or delete. | Yes |
How the resource tools work
Everything an agent does goes through eight generic tools, thinger_resource_describe, _list, _get, _create, _update, _delete, _clone and _call. Instead of one tool per resource, each one takes a type from the resource types table:
typenames the kind of resource:device,bucket,dashboard,alarm_rule… Data and files are types too:bucket_datais the time series of a Data Bucket,storage_filethe files of a file storage anddevice_resourcethe device resources of a connected device.idslocates one record, with its own ID and the IDs of the resources it hangs from, each under its name:{"device": "boiler"}for a device,{"device": "boiler", "property": "setpoint"}for one of its properties. The names are the ones of the API of the server (rulefor an alarm rule,typefor an asset type); the types table lists them for each type.
An agent starts with thinger_resource_describe: without arguments it lists every type and the concepts of the platform; with a type, it shows its IDs, fields, actions and examples, read from the API of your server. Then it lists records to find their IDs, and reads, creates or changes them. Operations that are not create, read, update or delete, such as calling a device resource, verifying a domain or testing an alarm rule, are actions run with thinger_resource_call:
{
"type": "device_resource",
"action": "call",
"ids": { "device": "YOUR_DEVICE", "resource": "led" },
"body": true
}Actions that ask first
Actions with a high impact do not act on the first call. They answer with what they would do, and the agent runs them by calling again with confirm: true in the body. They are marked Asks first in the actions table: replacing every resource of a product profile at once, removing or killing a plugin, restarting a host or changing its settings, sending a real test notification, and publishing a dashboard app that deletes files.
Read-only mode
thinger mcp --read-only serves only what reads: thinger_resource_describe, _list, _get, and _call with the actions marked Read-only. Use it to let an agent explore an account without changing anything. The token still sets what it can read: see Permissions.
Common parameters
| Parameter | Taken by | Description |
|---|---|---|
profile | Every tool | Profile of the CLI to use for this call only: another server, or another account with its own credentials. Without it, the tool uses the default profile. See Profiles. |
user | Every tool except thinger_resource_describe | Account to act on, for an administrator working on someone else's account. With a token that is not an administrator's, the call fails. See Permissions. |
A parameter that a tool does not take is never ignored: the call fails with an input_error that names the parameter and lists the ones the tool takes. This way a misspelled argument shows up at once.
Errors
A tool that fails returns an error with a code and a message, written as Error [code]: message, for example Error [not_found]: …. The codes are the same as in the JSON output of the CLI: unauthorized, not_found, already_exists, input_error, server_error and the others listed there. A call your token does not allow fails with unauthorized: Error [unauthorized]: Forbidden: the token or the account is not allowed to do this (not authorized).
Tool reference
thinger_resource_describe
Describes a resource type: its IDs, its operations and actions, the filter its list takes, and the bodies of create, update, clone and each action, with the schemas and examples of the API of your server and the permission each one needs. Without type, it lists every type with a guide to the concepts of the platform: agents start here.
| Parameter | Type | Required | Description |
|---|---|---|---|
type | string | No | Type to describe. Omit it to list every type. |
profile | string | No | CLI profile (server and credentials) for this call only. Omit it to use the default profile. thinger_resource_list with type profile lists them. |
thinger_resource_list
Lists the records of a type, one JSON record per line with the ids to pass back, a page at a time. Search by ID or name, and filter by product, asset type, asset group, project, labels or any field of the records. On bucket_data it reads the time series of a Data Bucket, and on storage_file the files of a file storage.
| Parameter | Type | Required | Description |
|---|---|---|---|
type | string | Yes | Resource type. See Resource types. |
ids | object | No | IDs that locate the record and its parents, each under its name, as the types table shows: {"device": "boiler"}, or {"device": "boiler", "property": "setpoint"} for a property of that device. |
filter | object | No | Filters as an object, for example {"product": "greenhouse"}. A field of the records filters by exact value; nested fields use dots. Alarm instances also filter by state and severity. Types with their own filter, such as bucket_data (time range, aggregation, device) or storage_file (folder), take only its keys: thinger_resource_describe shows them. |
search | string | No | Text to look for in IDs and names, partial and case insensitive. |
count | number | No | Page size. For bucket_data, the number of samples to return. |
index | number | No | Position of the first record, to read the next pages. |
user | string | No | Account to act on, when it is not yours. Needs an administrator token. Omit it to act on your own account. |
profile | string | No | CLI profile (server and credentials) for this call only. Omit it to use the default profile. thinger_resource_list with type profile lists them. |
thinger_resource_get
Reads one record as JSON, located by ids. Single resources (device_callback, product_profile_code) take only the IDs of their parent. It also reads a text file of a file storage (storage_file) and a guide for agents (doc).
| Parameter | Type | Required | Description |
|---|---|---|---|
type | string | Yes | Resource type. See Resource types. |
ids | object | No | IDs that locate the record and its parents, each under its name, as the types table shows: {"device": "boiler"}, or {"device": "boiler", "property": "setpoint"} for a property of that device. |
full | boolean | No | For plugins of the catalog: include the product code and the console dashboard of the plugin. |
user | string | No | Account to act on, when it is not yours. Needs an administrator token. Omit it to act on your own account. |
profile | string | No | CLI profile (server and credentials) for this call only. Omit it to use the default profile. thinger_resource_list with type profile lists them. |
thinger_resource_create
Creates a record from body, with the fields thinger_resource_describe shows. The ID of the new record goes in ids or in the ID field of the body. A projects list in the body also adds the new record to those projects. On bucket_data it writes samples to a Data Bucket, and on storage_file it writes a file.
Not served in read-only mode.
| Parameter | Type | Required | Description |
|---|---|---|---|
type | string | Yes | Resource type. See Resource types. |
ids | object | No | IDs that locate the record and its parents, each under its name, as the types table shows: {"device": "boiler"}, or {"device": "boiler", "property": "setpoint"} for a property of that device. |
body | object or array | No | Fields of the new record. An array creates several at once, where the type allows it (properties, samples of bucket_data). |
user | string | No | Account to act on, when it is not yours. Needs an administrator token. Omit it to act on your own account. |
profile | string | No | CLI profile (server and credentials) for this call only. Omit it to use the default profile. thinger_resource_list with type profile lists them. |
thinger_resource_update
Updates a resource with the fields in body and keeps the fields you leave out. Property values are replaced, unless you set merge. A projects list in the body sets the projects the resource belongs to. On storage_file it overwrites the file.
Not served in read-only mode.
| Parameter | Type | Required | Description |
|---|---|---|---|
type | string | Yes | Resource type. See Resource types. |
ids | object | No | IDs that locate the record and its parents, each under its name, as the types table shows: {"device": "boiler"}, or {"device": "boiler", "property": "setpoint"} for a property of that device. |
body | object | Yes | Fields to change. |
merge | boolean | No | Merge the body into the saved value (JSON merge) instead of replacing it. For properties and brands. |
user | string | No | Account to act on, when it is not yours. Needs an administrator token. Omit it to act on your own account. |
profile | string | No | CLI profile (server and credentials) for this call only. Omit it to use the default profile. thinger_resource_list with type profile lists them. |
thinger_resource_delete
Deletes the record ids locates, or the file of a storage_file. It is immediate and cannot be undone: agents are told to confirm with you first.
Not served in read-only mode.
| Parameter | Type | Required | Description |
|---|---|---|---|
type | string | Yes | Resource type. See Resource types. |
ids | object | No | IDs that locate the record and its parents, each under its name, as the types table shows: {"device": "boiler"}, or {"device": "boiler", "property": "setpoint"} for a property of that device. |
user | string | No | Account to act on, when it is not yours. Needs an administrator token. Omit it to act on your own account. |
profile | string | No | CLI profile (server and credentials) for this call only. Omit it to use the default profile. thinger_resource_list with type profile lists them. |
thinger_resource_clone
Copies the record ids locates under a new ID. The body holds the new ID in the ID field of the type, for example {"device": "sensor_02"}, or {"rule": "rule_02"} for an alarm rule, and optionally a new name, description and enabled state.
Not served in read-only mode.
| Parameter | Type | Required | Description |
|---|---|---|---|
type | string | Yes | Resource type. See Resource types. |
ids | object | Yes | IDs that locate the record and its parents, each under its name, as the types table shows: {"device": "boiler"}, or {"device": "boiler", "property": "setpoint"} for a property of that device. |
body | object | Yes | New ID and the fields to change in the copy. |
user | string | No | Account to act on, when it is not yours. Needs an administrator token. Omit it to act on your own account. |
profile | string | No | CLI profile (server and credentials) for this call only. Omit it to use the default profile. thinger_resource_list with type profile lists them. |
thinger_resource_call
Runs an action of a resource that is not create, read, update or delete: call a device resource, send data as a device, verify a domain, test an alarm rule, run a plugin's API, publish a dashboard app. See Actions. Actions with a high impact first answer with what they would do, and act only when called again with confirm: true in the body.
| Parameter | Type | Required | Description |
|---|---|---|---|
type | string | Yes | Resource type. Only the types with actions. |
action | string | Yes | Action name, for example call or verify. Each type has its own: see Actions. |
ids | object | No | IDs that locate the record and its parents, each under its name, as the types table shows: {"device": "boiler"}, or {"device": "boiler", "property": "setpoint"} for a property of that device. |
body | any | No | Input of the action, when it takes one. confirm: true runs an action that asks first. |
query | object | No | Query parameters of the action, when it takes them: the call of a plugin, the log of a host. |
user | string | No | Account to act on, when it is not yours. Needs an administrator token. Omit it to act on your own account. |
profile | string | No | CLI profile (server and credentials) for this call only. Omit it to use the default profile. thinger_resource_list with type profile lists them. |
Resource types
Every type the thinger_resource_* tools can reach, with the names of its ids, outermost first. The operations name the tool that runs each one:
| Operation | Tool |
|---|---|
| list | thinger_resource_list |
| get | thinger_resource_get |
| create | thinger_resource_create |
| update | thinger_resource_update |
| merge | thinger_resource_update with merge: true: merges the body into the saved value. |
| delete | thinger_resource_delete |
| clone | thinger_resource_clone |
| projects | The projects field of a create or update body: the projects the resource belongs to. |
Types marked Administrator are the administration of the server: they need an administrator token. See Permissions.
| Type | Description | ids | Operations | Administrator |
|---|---|---|---|---|
device | Devices of the account: IOTMP, MQTT, HTTP and virtual devices. | device | list, get, create, update, delete, clone, projects | |
product | Products: the shared configuration and profile of a fleet of devices. | product | list, get, create, update, delete, clone, projects | |
bucket | Data Buckets: time series data. Read and write their data with the type bucket_data. | bucket | list, get, create, update, delete, clone, projects | |
dashboard | Dashboards. Custom ones are apps on the Dashboard SDK, created, developed and published with the init, dev and publish actions. | dashboard | list, get, create, update, delete, clone, projects | |
endpoint | Endpoints: outgoing HTTP calls, emails and notifications. | endpoint | list, get, create, update, delete, clone, projects | |
storage | File storages. Their files are the type storage_file. | storage | list, get, create, update, delete, clone, projects | |
asset_type | Asset types: a category of devices, with its own properties. | type | list, get, create, update, delete, clone, projects | |
asset_group | Asset groups: a set of devices, such as a site, with its own properties. | group | list, get, create, update, delete, clone, projects | |
project | Projects: group resources of any type to share them or show them together. | project | list, get, create, update, delete, clone | |
token | Access tokens of the account, with their permissions. | token | list, get, create, update, delete, clone, projects | |
alarm_rule | Alarm rules: conditions on device or bucket data that raise alarms. | rule | list, get, create, update, delete, clone, projects | |
alarm_instance | Alarms raised by the rules. Update one to acknowledge, shelve or clear it. | instance | list, get, update, delete, projects | |
claim | Device claims: codes that let end users take ownership of a device. | claim | list, get, create, update, delete, clone, projects | |
property | Properties of the account: JSON values stored on the account. | property | list, get, create, update, merge, delete, clone | |
role | Roles: named sets of permissions for the members of a project. | role | list, get, create, update, delete, clone | |
sync | Syncs: shared semaphores with slots that devices or scripts take to coordinate. | sync | list, get, create, update, delete, clone, projects | |
plugin | Plugins installed on the account. Install and control them with their actions; call their API with the call action. | plugin | list, get | |
user | User accounts of the server. | user | list, get, create, update, delete | Yes |
host | Hosts of the server cluster. | host | list, get, create, update, delete | Yes |
domain | Custom domains the server answers on. | domain | list, get, create, update, delete | Yes |
brand | Brands: the look and the email settings of the console on a domain. | brand | list, get, create, update, merge, delete | Yes |
oauth_client | OAuth2 clients: applications allowed to sign users in against the server. | oauth_client | list, get, create, update, delete | Yes |
identity_provider | Identity providers: external sign-in for the console (OpenID Connect, OAuth2). | identity_provider | list, get, create, update, delete | Yes |
proxy | Proxies: services the server exposes through its own address. | proxy | list, get, create, update, delete | Yes |
sync_lock | Locks of a sync: the slots currently taken. | sync, lock | list, get, create, update, delete | |
device_property | Properties of a device: its structured state, such as configuration or calibration. | device, property | list, get, create, update, merge, delete, clone | |
device_token | Access tokens limited to one device and some of its device resources. | device, token | list, create, delete | |
device_bucket | Data Buckets that hold data of a device (list only). | device, bucket | list | |
device_bucket_tag | Tags of a Data Bucket for one device. | device, bucket, tag | list, get | |
device_service | Services a device exposes, such as a web interface or VNC. | device, service | list, get | |
device_callback | HTTP callback of a device: what the server does with the data it receives. | device | get, update (single resource of its parent) | |
product_property | Properties of a product. | product, property | list, get, create, update, merge, delete, clone | |
product_profile_api | API resources a product adds to its devices. | product, resource | list, get, create, update, delete | |
product_profile_bucket | Data Buckets a product keeps for each of its devices. | product, resource | list, get, create, update, delete | |
product_profile_property | Properties a product writes on each of its devices. | product, resource | list, get, create, update, delete | |
product_profile_autoprovision | Autoprovisioning rules: which connecting devices join the product. | product, resource | list, get, create, update, delete | |
product_profile_flow | Data flows of a product. | product, resource | list, get, create, update, delete | |
product_profile_code | Code of a product: the JavaScript the server runs for its devices. | product | get, update (single resource of its parent) | |
product_service | Services a product exposes on its devices. | product, service | list, get, create, update, delete | |
bucket_tag | Tags of a Data Bucket and their values. | bucket, tag | list, get | |
bucket_export | Exports of a Data Bucket: files generated from its data. | bucket, file | list, create, delete | |
plugin_property | Properties of a plugin, usually its configuration. | plugin, property | list, get, create, update, merge, delete, clone | |
asset_type_property | Properties of an asset type. | type, property | list, get, create, update, merge, delete, clone | |
asset_group_property | Properties of an asset group. | group, property | list, get, create, update, merge, delete, clone | |
project_property | Properties of a project. | project, property | list, get, create, update, merge, delete, clone | |
project_member | Members a project is shared with, and their roles. | project, member | list, get, create, update, delete | |
project_role | Roles defined in a project. | project, role | list, get, create, update, delete, clone | |
bucket_data | The time series of a Data Bucket: list reads samples (latest, a time range or the last minutes, with optional aggregation and one series per device), create writes samples when its data source accepts writes from the API. | bucket | list, create | |
storage_file | Files of a file storage, by path: list, read text files, write text or upload files and folders of your computer (binary too), and delete. | storage, file | list, get, create, update, delete | |
device_resource | The device resources a connected device exposes, with their inputs and outputs: the ones its firmware declares and the API resources its product adds. The device must be online. | device, resource | list | |
doc | The guides for agents that come with the CLI: see Guides. | doc | list, get | |
profile | The profiles of the CLI: each one is a server with its own credentials. Another account on the same server is reached with user, not with a profile. | profile | list |
Actions
Actions are run with thinger_resource_call, giving the type, the action and, for most of them, the ids. Use thinger_resource_describe with the type to see the body an action takes. Read-only actions are also served in read-only mode; actions that ask first need confirm: true to act (see Actions that ask first).
| Type | Action | Description | Read-only | Asks first |
|---|---|---|---|---|
device | stats | Daily usage of the device over the last month: traffic and calls. | Yes | |
device | send | Sends data to the server on behalf of an HTTP device, as the device itself would. The server runs the callback configured for the device: write a Data Bucket, set a property or call an endpoint. | ||
device | overview | Daily usage of all the devices of the account over the last month and, with locations, the last known position of each connected device. | Yes | |
product | export | The product with everything it depends on, as one JSON document, to back it up or recreate it. | Yes | |
bucket | import | Loads the records of a CSV file already uploaded to a file storage into the Data Bucket. The way to load a long history. | ||
dashboard | init | Creates a dashboard app: a TypeScript project on the Dashboard SDK from one of the templates of the SDK package (React by default, or Angular), with a thinger.json manifest for the dev and publish actions, and an AGENTS.md with the rules of the dashboard frame. | ||
dashboard | dev | Returns a link that opens the app from its own development server (npm run dev, ng serve) as a standalone page connected to your server, with a temporary token and the context you choose. The app gets real data and reloads on every change. Each call replaces the token of the previous link. | ||
dashboard | publish | Uploads the build of an app to a public file storage and points dashboards at it. Both parts are optional: upload a new build, point more dashboards at an app already uploaded, or both. It warns when the SDK of the app needs a newer server, when a newer SDK is on npm, or when a page loads the deprecated thinger-dashboard.js script. Deleting the files that are not in the upload (prune) asks first. | Yes | |
endpoint | call | Runs the endpoint with body as its payload and returns its answer. | ||
alarm_rule | test_rule | Evaluates a rule, saved or given in body, without raising alarms or sending notifications. | Yes | |
alarm_rule | test_source | Reads one data source as the rule would. | Yes | |
alarm_rule | test_notification | Sends the notification of the rule for real, through its endpoints: people receive it. | Yes | |
alarm_instance | stats | How many alarms there are in each state, without listing them. | Yes | |
plugin | install | Installs a plugin of the catalog with the settings in body. It is installed stopped: start it next. | ||
plugin | upgrade | Upgrades the plugin to another version, keeping its data. It is left stopped: start it next. | ||
plugin | remove | Uninstalls the plugin and deletes its files, data and properties. | Yes | |
plugin | start | Starts the plugin. | ||
plugin | stop | Stops the plugin. | ||
plugin | restart | Restarts the plugin. | ||
plugin | pause | Pauses the plugin. | ||
plugin | unpause | Resumes a paused plugin. | ||
plugin | kill | Kills the plugin. | Yes | |
plugin | public | Makes the web interface of the plugin reachable without signing in. | ||
plugin | private | Makes the web interface of the plugin require signing in again. | ||
plugin | call | Calls the API that an installed plugin serves, at a path of its own. What it offers depends on the plugin: see its page in the plugin catalog. | ||
host | logs | The last lines of the log of the host, as text. | Yes | |
host | restart | Restarts the host: its devices and users lose the connection meanwhile. | Yes | |
host | read_settings | Reads the settings of the host. | Yes | |
host | update_settings | Merges body into the settings of the host: keys left out stay, and null removes one. It takes effect after the restart action. | Yes | |
domain | verify | Checks that the domain resolves to the server, after you configure its DNS. | ||
brand | test_email | Sends a test email with the email settings of the brand. | ||
product_profile_api | replace_all | Replaces every API resource of the product at once with body. | Yes | |
product_profile_api | call | Calls an API resource of a product for the product as a whole, as an external system that feeds data in would. The API resource needs a device resolver in the product code to find the device of each payload. To call it for one device, use the call action of device_resource. | ||
product_profile_bucket | replace_all | Replaces every bucket of the product profile at once with body. | Yes | |
product_profile_property | replace_all | Replaces every property of the product profile at once with body. | Yes | |
product_profile_autoprovision | replace_all | Replaces every autoprovisioning rule of the product at once with body. | Yes | |
product_profile_flow | replace_all | Replaces every data flow of the product at once with body. | Yes | |
device_resource | call | Calls a device resource of a connected device and returns its output. With a body it runs the resource with that input; without one it only reads its output. |
Guides
The MCP server also serves guides written for agents. They come with the CLI and are offered in two ways, with the same content:
- As MCP resources, with the URIs below. Clients that support resources let you attach them to a conversation.
- As the type
doc:thinger_resource_listlists them andthinger_resource_getwithids{"doc": "concepts"}reads one, for agents and clients that only use tools.
| Guide | Resource | Content |
|---|---|---|
concepts | thinger://concepts | How projects, devices, products, Data Buckets, asset types and groups, properties, alarms, endpoints, file storages, tokens, dashboards and events relate, and which data source fits each need. |
product-code | thinger://product-code | The JavaScript a product runs: functions that compute device resources (virtual devices), payload transforms and the device resolver. |
server-admin | thinger://server-admin | For administrators: host settings and restarts, custom domains and brands, user accounts, OAuth2 clients, identity providers and proxies, with their side effects. |
dashboard-sdk | thinger://dashboard-sdk | The Dashboard SDK reference: install it, run apps in the console or standalone, routing, context and every call. |
dashboard-sdk-types | thinger://dashboard-sdk-types | The TypeScript declarations of the Dashboard SDK. |
These guides are not the documentation of this site. To give an agent this documentation, see Docs for agents.