Skip to content

AI & MCP

MCP tools

Every tool the Thinger.io MCP server offers to AI agents, with its parameters, and every resource type the agents can reach.

Reference19 min read

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.

PackageVersion
@thinger-io/cli0.5.1
@thinger-io/cli-core0.5.2

Tools ​

ToolDescriptionRead-only mode
thinger_resource_describeDescribes a resource type.Yes
thinger_resource_listLists the records of a type, one JSON record per line with the ids to pass back, a page at a time.Yes
thinger_resource_getReads one record as JSON, located by ids.Yes
thinger_resource_createCreates a record from body, with the fields thinger_resource_describe shows.
thinger_resource_updateUpdates a resource with the fields in body and keeps the fields you leave out.
thinger_resource_deleteDeletes the record ids locates, or the file of a storage_file.
thinger_resource_cloneCopies the record ids locates under a new ID.
thinger_resource_callRuns 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:

  • type names the kind of resource: device, bucket, dashboard, alarm_rule… Data and files are types too: bucket_data is the time series of a Data Bucket, storage_file the files of a file storage and device_resource the device resources of a connected device.
  • ids locates 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 (rule for an alarm rule, type for 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:

json
{
  "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 ​

ParameterTaken byDescription
profileEvery toolProfile 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.
userEvery tool except thinger_resource_describeAccount 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.

ParameterTypeRequiredDescription
typestringNoType to describe. Omit it to list every type.
profilestringNoCLI 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.

ParameterTypeRequiredDescription
typestringYesResource type. See Resource types.
idsobjectNoIDs 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.
filterobjectNoFilters 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.
searchstringNoText to look for in IDs and names, partial and case insensitive.
countnumberNoPage size. For bucket_data, the number of samples to return.
indexnumberNoPosition of the first record, to read the next pages.
userstringNoAccount to act on, when it is not yours. Needs an administrator token. Omit it to act on your own account.
profilestringNoCLI 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).

ParameterTypeRequiredDescription
typestringYesResource type. See Resource types.
idsobjectNoIDs 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.
fullbooleanNoFor plugins of the catalog: include the product code and the console dashboard of the plugin.
userstringNoAccount to act on, when it is not yours. Needs an administrator token. Omit it to act on your own account.
profilestringNoCLI 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.

ParameterTypeRequiredDescription
typestringYesResource type. See Resource types.
idsobjectNoIDs 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.
bodyobject or arrayNoFields of the new record. An array creates several at once, where the type allows it (properties, samples of bucket_data).
userstringNoAccount to act on, when it is not yours. Needs an administrator token. Omit it to act on your own account.
profilestringNoCLI 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.

ParameterTypeRequiredDescription
typestringYesResource type. See Resource types.
idsobjectNoIDs 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.
bodyobjectYesFields to change.
mergebooleanNoMerge the body into the saved value (JSON merge) instead of replacing it. For properties and brands.
userstringNoAccount to act on, when it is not yours. Needs an administrator token. Omit it to act on your own account.
profilestringNoCLI 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.

ParameterTypeRequiredDescription
typestringYesResource type. See Resource types.
idsobjectNoIDs 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.
userstringNoAccount to act on, when it is not yours. Needs an administrator token. Omit it to act on your own account.
profilestringNoCLI 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.

ParameterTypeRequiredDescription
typestringYesResource type. See Resource types.
idsobjectYesIDs 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.
bodyobjectYesNew ID and the fields to change in the copy.
userstringNoAccount to act on, when it is not yours. Needs an administrator token. Omit it to act on your own account.
profilestringNoCLI 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.

ParameterTypeRequiredDescription
typestringYesResource type. Only the types with actions.
actionstringYesAction name, for example call or verify. Each type has its own: see Actions.
idsobjectNoIDs 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.
bodyanyNoInput of the action, when it takes one. confirm: true runs an action that asks first.
queryobjectNoQuery parameters of the action, when it takes them: the call of a plugin, the log of a host.
userstringNoAccount to act on, when it is not yours. Needs an administrator token. Omit it to act on your own account.
profilestringNoCLI 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:

OperationTool
listthinger_resource_list
getthinger_resource_get
createthinger_resource_create
updatethinger_resource_update
mergethinger_resource_update with merge: true: merges the body into the saved value.
deletethinger_resource_delete
clonethinger_resource_clone
projectsThe 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.

TypeDescriptionidsOperationsAdministrator
deviceDevices of the account: IOTMP, MQTT, HTTP and virtual devices.devicelist, get, create, update, delete, clone, projects
productProducts: the shared configuration and profile of a fleet of devices.productlist, get, create, update, delete, clone, projects
bucketData Buckets: time series data. Read and write their data with the type bucket_data.bucketlist, get, create, update, delete, clone, projects
dashboardDashboards. Custom ones are apps on the Dashboard SDK, created, developed and published with the init, dev and publish actions.dashboardlist, get, create, update, delete, clone, projects
endpointEndpoints: outgoing HTTP calls, emails and notifications.endpointlist, get, create, update, delete, clone, projects
storageFile storages. Their files are the type storage_file.storagelist, get, create, update, delete, clone, projects
asset_typeAsset types: a category of devices, with its own properties.typelist, get, create, update, delete, clone, projects
asset_groupAsset groups: a set of devices, such as a site, with its own properties.grouplist, get, create, update, delete, clone, projects
projectProjects: group resources of any type to share them or show them together.projectlist, get, create, update, delete, clone
tokenAccess tokens of the account, with their permissions.tokenlist, get, create, update, delete, clone, projects
alarm_ruleAlarm rules: conditions on device or bucket data that raise alarms.rulelist, get, create, update, delete, clone, projects
alarm_instanceAlarms raised by the rules. Update one to acknowledge, shelve or clear it.instancelist, get, update, delete, projects
claimDevice claims: codes that let end users take ownership of a device.claimlist, get, create, update, delete, clone, projects
propertyProperties of the account: JSON values stored on the account.propertylist, get, create, update, merge, delete, clone
roleRoles: named sets of permissions for the members of a project.rolelist, get, create, update, delete, clone
syncSyncs: shared semaphores with slots that devices or scripts take to coordinate.synclist, get, create, update, delete, clone, projects
pluginPlugins installed on the account. Install and control them with their actions; call their API with the call action.pluginlist, get
userUser accounts of the server.userlist, get, create, update, deleteYes
hostHosts of the server cluster.hostlist, get, create, update, deleteYes
domainCustom domains the server answers on.domainlist, get, create, update, deleteYes
brandBrands: the look and the email settings of the console on a domain.brandlist, get, create, update, merge, deleteYes
oauth_clientOAuth2 clients: applications allowed to sign users in against the server.oauth_clientlist, get, create, update, deleteYes
identity_providerIdentity providers: external sign-in for the console (OpenID Connect, OAuth2).identity_providerlist, get, create, update, deleteYes
proxyProxies: services the server exposes through its own address.proxylist, get, create, update, deleteYes
sync_lockLocks of a sync: the slots currently taken.sync, locklist, get, create, update, delete
device_propertyProperties of a device: its structured state, such as configuration or calibration.device, propertylist, get, create, update, merge, delete, clone
device_tokenAccess tokens limited to one device and some of its device resources.device, tokenlist, create, delete
device_bucketData Buckets that hold data of a device (list only).device, bucketlist
device_bucket_tagTags of a Data Bucket for one device.device, bucket, taglist, get
device_serviceServices a device exposes, such as a web interface or VNC.device, servicelist, get
device_callbackHTTP callback of a device: what the server does with the data it receives.deviceget, update (single resource of its parent)
product_propertyProperties of a product.product, propertylist, get, create, update, merge, delete, clone
product_profile_apiAPI resources a product adds to its devices.product, resourcelist, get, create, update, delete
product_profile_bucketData Buckets a product keeps for each of its devices.product, resourcelist, get, create, update, delete
product_profile_propertyProperties a product writes on each of its devices.product, resourcelist, get, create, update, delete
product_profile_autoprovisionAutoprovisioning rules: which connecting devices join the product.product, resourcelist, get, create, update, delete
product_profile_flowData flows of a product.product, resourcelist, get, create, update, delete
product_profile_codeCode of a product: the JavaScript the server runs for its devices.productget, update (single resource of its parent)
product_serviceServices a product exposes on its devices.product, servicelist, get, create, update, delete
bucket_tagTags of a Data Bucket and their values.bucket, taglist, get
bucket_exportExports of a Data Bucket: files generated from its data.bucket, filelist, create, delete
plugin_propertyProperties of a plugin, usually its configuration.plugin, propertylist, get, create, update, merge, delete, clone
asset_type_propertyProperties of an asset type.type, propertylist, get, create, update, merge, delete, clone
asset_group_propertyProperties of an asset group.group, propertylist, get, create, update, merge, delete, clone
project_propertyProperties of a project.project, propertylist, get, create, update, merge, delete, clone
project_memberMembers a project is shared with, and their roles.project, memberlist, get, create, update, delete
project_roleRoles defined in a project.project, rolelist, get, create, update, delete, clone
bucket_dataThe 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.bucketlist, create
storage_fileFiles 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, filelist, get, create, update, delete
device_resourceThe 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, resourcelist
docThe guides for agents that come with the CLI: see Guides.doclist, get
profileThe 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.profilelist

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

TypeActionDescriptionRead-onlyAsks first
devicestatsDaily usage of the device over the last month: traffic and calls.Yes
devicesendSends 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.
deviceoverviewDaily usage of all the devices of the account over the last month and, with locations, the last known position of each connected device.Yes
productexportThe product with everything it depends on, as one JSON document, to back it up or recreate it.Yes
bucketimportLoads the records of a CSV file already uploaded to a file storage into the Data Bucket. The way to load a long history.
dashboardinitCreates 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.
dashboarddevReturns 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.
dashboardpublishUploads 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
endpointcallRuns the endpoint with body as its payload and returns its answer.
alarm_ruletest_ruleEvaluates a rule, saved or given in body, without raising alarms or sending notifications.Yes
alarm_ruletest_sourceReads one data source as the rule would.Yes
alarm_ruletest_notificationSends the notification of the rule for real, through its endpoints: people receive it.Yes
alarm_instancestatsHow many alarms there are in each state, without listing them.Yes
plugininstallInstalls a plugin of the catalog with the settings in body. It is installed stopped: start it next.
pluginupgradeUpgrades the plugin to another version, keeping its data. It is left stopped: start it next.
pluginremoveUninstalls the plugin and deletes its files, data and properties.Yes
pluginstartStarts the plugin.
pluginstopStops the plugin.
pluginrestartRestarts the plugin.
pluginpausePauses the plugin.
pluginunpauseResumes a paused plugin.
pluginkillKills the plugin.Yes
pluginpublicMakes the web interface of the plugin reachable without signing in.
pluginprivateMakes the web interface of the plugin require signing in again.
plugincallCalls 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.
hostlogsThe last lines of the log of the host, as text.Yes
hostrestartRestarts the host: its devices and users lose the connection meanwhile.Yes
hostread_settingsReads the settings of the host.Yes
hostupdate_settingsMerges body into the settings of the host: keys left out stay, and null removes one. It takes effect after the restart action.Yes
domainverifyChecks that the domain resolves to the server, after you configure its DNS.
brandtest_emailSends a test email with the email settings of the brand.
product_profile_apireplace_allReplaces every API resource of the product at once with body.Yes
product_profile_apicallCalls 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_bucketreplace_allReplaces every bucket of the product profile at once with body.Yes
product_profile_propertyreplace_allReplaces every property of the product profile at once with body.Yes
product_profile_autoprovisionreplace_allReplaces every autoprovisioning rule of the product at once with body.Yes
product_profile_flowreplace_allReplaces every data flow of the product at once with body.Yes
device_resourcecallCalls 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_list lists them and thinger_resource_get with ids {"doc": "concepts"} reads one, for agents and clients that only use tools.
GuideResourceContent
conceptsthinger://conceptsHow 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-codethinger://product-codeThe JavaScript a product runs: functions that compute device resources (virtual devices), payload transforms and the device resolver.
server-adminthinger://server-adminFor administrators: host settings and restarts, custom domains and brands, user accounts, OAuth2 clients, identity providers and proxies, with their side effects.
dashboard-sdkthinger://dashboard-sdkThe Dashboard SDK reference: install it, run apps in the console or standalone, routing, context and every call.
dashboard-sdk-typesthinger://dashboard-sdk-typesThe 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.

See also ​