Devices MCP tools
Browse all 6 the platform MCP tools for devices, with input schemas, output schemas, and behavior hints for building AI agent integrations
This page documents 6 tools in the devices group. Return to the complete MCP tool reference to browse another group.
Select a tool to inspect its schemas and behavior. Schema links open the exact definition in GitHub.
listDevicesList DevicesRead onlyList ITAM devices for an organization. Use createDevice to issue a PENDING device and a one-shot enrollment token for the agent installer. Device states: PENDING (enrollment token issued, agent has never checked in), ACTIVE (agent heartbeating), REVOKED (enrollment revoked). Use last_seen_at as the staleness signal. latest_postures is empty unless include_postures is true; when loaded it holds the newest result per check_key and is empty for PENDING devices. Page with size and cursor; when next_cursor is present, pass it as cursor on the next call.
getDeviceGet DeviceRead onlyGet one ITAM device by ID (soft-deleted devices are not returned). Same state machine as listDevices: PENDING (enrollment token issued, agent has never checked in), ACTIVE (agent heartbeating), REVOKED (enrollment revoked). Use last_seen_at as the staleness signal. latest_postures is empty unless include_postures is true; when loaded it holds the newest result per check_key and is empty for PENDING devices.
createDeviceCreate DeviceWrites dataCreate a PENDING ITAM device and return a one-shot enrollment token (plus server_url and enrollment_url) for the agent installer. The plaintext token is shown only in this response; only its hash is stored. The token also expires after a deployment-configured lifetime (7 days by default), so hand it to the installer now instead of storing it for a later retry: exchanging an expired token fails with enrollment token expired and leaves the device PENDING, and you must call createDevice again to issue a fresh device and token. Optionally assign an owner with owner_id (MembershipProfile GID in the same organization).
revokeDeviceRevoke DeviceWrites dataIrreversibly revoke a device enrollment. Immediately invalidates the device agent API key so the agent stops authenticating and reporting; there is no un-revoke tool. Safe to call more than once: state stays REVOKED and revoked_at keeps its original value. Call this before deleteDevice.
deleteDeviceDelete DeviceWrites dataSoft-delete a device. The device must already be REVOKED — call revokeDevice first, otherwise the call fails with the error device cannot be deleted. After success the device stops appearing in listDevices/getDevice; enrollment tokens for the device are removed. Eligible orphan rows are later hard-deleted by the ITAM garbage collector.
setDeviceOwnerSet Device OwnerWrites dataSet or clear the owner of an ITAM device. owner_id is required: pass a MembershipProfile GID belonging to the same organization as the device to assign, or null to clear. Omitting the field is invalid.