# Devices MCP tools

This page documents **6 tools** in the devices group. Return to the [complete MCP tool reference](/docs/developers/api/mcp/tools) to browse another group.

Select a tool to inspect its schemas and behavior. Schema links open the exact definition in GitHub.

### `listDevices` — List Devices

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

- **Input:** [`ListDevicesInput`](/docs)
- **Output:** [`ListDevicesOutput`](/docs)
- **Behavior:** Read only · Non-destructive · Idempotent · Closed world
- **Source:** [specification.yaml · L14929–L14940 ↗](/docs)

### `getDevice` — Get Device

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

- **Input:** [`GetDeviceInput`](/docs)
- **Output:** [`GetDeviceOutput`](/docs)
- **Behavior:** Read only · Non-destructive · Idempotent · Closed world
- **Source:** [specification.yaml · L14941–L14952 ↗](/docs)

### `createDevice` — Create Device

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

- **Input:** [`CreateDeviceInput`](/docs)
- **Output:** [`CreateDeviceOutput`](/docs)
- **Behavior:** Writes data · Non-destructive · Non-idempotent · Closed world
- **Source:** [specification.yaml · L14953–L14964 ↗](/docs)

### `revokeDevice` — Revoke Device

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

- **Input:** [`RevokeDeviceInput`](/docs)
- **Output:** [`RevokeDeviceOutput`](/docs)
- **Behavior:** Writes data · Destructive · Idempotent · Closed world
- **Source:** [specification.yaml · L14965–L14976 ↗](/docs)

### `deleteDevice` — Delete Device

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

- **Input:** [`DeleteDeviceInput`](/docs)
- **Output:** [`DeleteDeviceOutput`](/docs)
- **Behavior:** Writes data · Destructive · Idempotent · Closed world
- **Source:** [specification.yaml · L14977–L14988 ↗](/docs)

### `setDeviceOwner` — Set Device Owner

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

- **Input:** [`SetDeviceOwnerInput`](/docs)
- **Output:** [`SetDeviceOwnerOutput`](/docs)
- **Behavior:** Writes data · Non-destructive · Idempotent · Closed world
- **Source:** [specification.yaml · L14989–L15000 ↗](/docs)