---
name: jumpcloud-device-fleet
description: Inventory and operate a JumpCloud-managed device fleet — list and filter devices, check OS and agent versions, review patch and vulnerability posture, run remote commands, manage device groups, and lock, restart, or erase a machine. Use when the user asks about their laptops, endpoints, machines, MDM, patching, a lost or stolen device, or running a script across the fleet.
license: MIT
compatibility: Requires the JumpCloud MCP server (https://mcp.jumpcloud.com/v1) connected with an admin account or API key.
metadata:
  author: jumpcloud
  version: "1.1.0"
---

# Operating a JumpCloud device fleet

Devices are managed individually and in **device groups**. Groups are how commands and
policies reach many machines at once, so most fleet-wide work is really group work.

Read the safety tiers in the `jumpcloud-admin` skill before any write. Device tools act on
hardware someone may be actively using — a restart during a presentation is a real cost.

## Fleet questions

Answer these with one `search_api_execute` call, not a listing loop:

> "How many devices per OS version?"
> "Which devices haven't checked in for 30 days?"
> "Devices running an agent older than the current release"
> "Macs on an OS version below 15"

Use `devices_list` for a straightforward full or filtered inventory, and `device_get` when
you already have an ID. Apple-specific inventory lives in `applemdm_abm_devices` and
`applemdm_os_versions`; `applemdms_list` shows the configured MDM instances.

Stale devices are ambiguous — a machine that has not checked in could be decommissioned,
shelved, or compromised. Report the gap; do not assume which.

## Patch and vulnerability posture

Work top-down so you can stop early when the answer is "fine":

1. `patch_summary_get` — fleet-wide rollup.
2. `patch_critical_summary_get` — how bad the critical tail is.
3. `patch_critical_devices_list` — the actual remediation worklist, by device.
4. `patch_coverage_get` — whether gaps are policy coverage holes rather than failures.

**Per-device and per-group patch status requires a two-step call.**
`patch_devices_list` and `patch_device_groups_list` are scoped by update: first call
`patch_kbs_list` to discover the individual KB entries and their `update_id` values, then
pass those IDs into the device or device-group call. Going straight to
`patch_devices_list` without update IDs will not answer "which devices are missing patch X".

A device missing patches because it is offline needs a different fix than one missing
patches because no policy targets it. `patch_coverage_get` is what distinguishes them, so
check it before recommending remediation.

## Remote commands

`command_run` executes with root/SYSTEM privileges on every associated target. Treat it as
the highest-consequence tool in the fleet surface.

Before running anything:

1. `command_get` and **read the script body**. Say what it actually does in one sentence.
   If you cannot explain it, do not run it.
2. `command_devices_list` and `command_device_groups_list` to establish the blast radius.
   State the count and name the groups.
3. Confirm both the script and the target set with the user.

After running, `command_results_list` and `command_result_get` retrieve output. Commands
are asynchronous — results are not immediate. **A command sent to an offline device queues
and runs when the device next checks in**, so a missing result is not the same as a
failure. Say which one you're reporting.

Never dump raw command output. Summarize it: "Completed on 8 of 10 devices; 2 timed out,
both offline since Tuesday" is useful, a wall of stdout is not.

Use `command_manage_associations` to change targeting. Widening a command's target set is
as consequential as running it, because the next execution hits the new machines.

## Device groups

`device_groups_list`, `device_group_get`, and `device_group_membership` read the structure;
`device_group_create` and `manage_device_group_membership` change it.

`device_group_delete` is destructive beyond the group itself — the policies, commands, and
patch schedules bound to it stop applying to its members. Before deleting, read
`device_group_membership` and `policies_list` and tell the user which machines lose which
protections.

## Lock, restart, shutdown, erase

All four are destructive. Ordered by severity:

| Tool | Effect | When |
|---|---|---|
| `device_lock` | Screen locks immediately; data intact | Default response to a missing or suspect device. Reversible. |
| `device_restart` | Reboots now; unsaved work lost | Applying an update or clearing a hung state. |
| `device_shutdown` | Powers off; stays offline until physically restarted | Rarely the right answer remotely — you cannot power it back on. |
| `device_erase` | Wipes the machine | Confirmed theft or a hostile departure. No undo. |

Before any of these, `device_get` the target and echo the machine and its assigned user by
name. For `device_erase`, require confirmation of that specific device by name, and state
explicitly that local-only data is unrecoverable. Never erase more than one device in
response to a single confirmation.

For a lost device, `device_lock` first — it is immediate, reversible, and buys time to
determine whether the machine is stolen or in a couch cushion.

## User–device binding

`bind_user_to_device` and `unbind_user_from_device` control local login. Unbinding removes
a person's ability to log into a machine but does not touch their directory account or SSO
access — say so, so nobody mistakes it for offboarding. The full sequence is in the
`jumpcloud-user-lifecycle` skill.