Devices MCP tools
View all 6 MCP platform tools for devices, with input schemes, output schemes and behavioral tips for building AI agent integrations
This page documents 6 tools in the device group. Back to complete MCP tool reference to browse another group.
Select a tool to inspect its schemes and behavior. The link scheme opens the exact definition inGitHub.
listDevicesList DevicesRead onlyList of ITAM devices for an organization. Use createDevice to issue a PENDING device and a one-shot sign-up token for the agent's installer. The device states: PENDING (the sign-up token issued, the agent never checked), ACTIVE (the agent's heartbeats), REVOKED (record revoked). Use last_seen_at as a stagnation signal. latest_postures is empty unless include_postures is true; when loaded, it holds the latest score per check_key and is empty for PENDING devices. Page with size and cursor; when next_cursor is present, as a cursor to the next call.
getDeviceGet DeviceRead onlyGet an ITAM device by ID (easy deleted devices are not returned). The same state machine as listDevices: PENDING (record token issued, the agent never checked), ACTIVE (the agent beats the heart), REVOKED (enrollment revoked). Use last_seen_at as a stagnation signal. latest_postures is empty unless include_postures is true; when loaded, it holds the latest result on check_key and is empty for PENDING devices.
createDeviceCreate DeviceWrites dataCreate a PENDING ITAM device and return a single-hit recording token (plus server_url and enrollment_url) to the agent's installer. The plaintext token is displayed only in this response; only its hash is stored. The token also expires after a configured implementation life (7 days by default), so give it to the installer now instead of storing it for subsequent withdrawal: the exchange of an expired token fails with the expired recording token and leaves the PENDING device and you need to call again to createDevice to issue a device and fresh token. Optional assign a owner with owner_id
revokeDeviceRevoke DeviceWrites dataIrrevocably cancels the registration of a device. Immediately invalidates the device agent key, so that the agent stops authenticating and reporting; there is no tool that will not be revoked. Security to call more than once: the state remains REVOKED and revoked_at retains its original value. Call this before deletingDevice.
deleteDeviceDelete DeviceWrites dataDelete a device gently. The device must have already been REVOKED – call revokeDevice first, otherwise the call fails with the error device cannot be deleted. After success, the device ceases to appear in listDevices/getDevice; the record tokens for the device are removed.
setDeviceOwnerSet Device OwnerWrites dataSet or delete the owner of an ITAM device. owner_id is required: pass a MembershipProfile GID belonging to the same organization as the device to be assigned or null to delete.