# MCP Tools

> The tools the CapaOne MCP server gives an AI agent, and what to ask them.

Source: https://docs.capaone.com/capaone/mcp-and-api/mcp-tools/  
Product: CapaOne — a separate CapaSystems product; do not apply this page to any other.

The tools the CapaOne MCP server gives an agent. Agents pick them on their own; this page is for
seeing what they can do and what to ask.

## At a glance

| Tool | Use it to | Try asking |
|---|---|---|
| `get_organization` | See which organization the connection belongs to: its name, ID and products. | "Which organization are you connected to?" |
| `list_filterable_fields` | Learn which device fields and operators search accepts, your custom inventory fields included. | "Which device fields can you filter on?" |
| `search_devices` | Find and count devices by any combination of fields, or by name and user. | "List the Windows devices that have not checked in for the last 30 days." |
| `group_devices` | Count the devices per value of a field, for example per computer model, OS version or application version. | "Which computer models do we have, and how many of each?" |
| `get_device` | Read one device: its details and, in the same call, its hardware, software, driver, security, user or custom inventory, its configurations and its patches. | "Why is LAPTOP-0042 not patch compliant, and is its disk encrypted?" |
| `get_patch_compliance` | Read software patch compliance now and per day, and the applications behind it, for example the ones failing to install. | "Has our patch compliance improved since last Monday, and which applications are failing?" |
| `get_security_posture` | Count the devices scoring good, fair or poor on antivirus, encryption, firewall, Windows Update and pending reboot. | "How many of our devices are not encrypted?" |
| `get_vulnerabilities` | Read the latest vulnerability scan or its history, or list the most severe CVEs or the ones a scan found new, gone or persistent. | "How many critical CVEs do we have compared with a week ago, and which ones are new?" |
| `get_events` | Summarize the Windows events devices reported, list the devices with the most of them or the events themselves, and look up event sources and IDs. | "What are the top crash sources this week, and which devices crash the most?" |
| `get_elevations` | Count Admin On Demand elevations per user or per process, or read one device's elevation log. | "Who used Admin On Demand the most last month, and what was elevated on LAPTOP-0042?" |

Every tool is read-only and limited to the organization your API key belongs to.

Each tool's full description and arguments come from the server itself (`tools/list`), so agents
always see the current version. To read them, look at the tool in your MCP client, or connect with
the MCP Inspector as described in
[Connect an MCP Client](/capaone/mcp-and-api/connect-an-mcp-client/#test-the-connection).

## How an agent uses them

The server's instructions and the tool descriptions lead an agent through them in this order:

1. Asked which organization it is connected to, it calls `get_organization`.
2. Before filtering, it calls `list_filterable_fields` once. Then `search_devices` finds and counts
   devices, and `group_devices` counts them per value.
3. For exact filter values, such as computer models or application names, it calls `group_devices`.
4. For one device, it takes the `id` from the search and calls `get_device` with the sections it
   needs, `get_events` or `get_elevations`.
5. For a hardware, security or custom inventory, `get_device` returns the overview of categories
   first. The agent then asks for the category it needs.
6. For the organization as a whole, it calls `get_patch_compliance`, `get_security_posture`,
   `get_vulnerabilities`, `get_events` and `get_elevations`. It counts anything else, such as OS
   versions, with `search_devices` and `group_devices`.
7. To see what is behind a summary, it calls the same tool with another `view`:
   `get_patch_compliance` for the applications, `get_vulnerabilities` for the CVEs, and
   `get_events` for the devices, the events and the exact sources and event IDs to narrow by.
8. For a change over time, it uses the history of `get_patch_compliance` and
   `get_vulnerabilities`, or a time window in `get_events`. Device search has no history, so the
   agent says so rather than estimating last week from today.

## Examples

### Search devices

Windows 10 devices that have not checked in during the last 30 days, oldest check-in first:

```json title="search_devices arguments"
{
  "anyOf": [
    {
      "allOf": [
        { "field": "osName", "operator": "CONTAINS", "values": ["Windows 10"] },
        { "field": "lastCheckIn", "operator": "WITHIN_LAST_DAYS", "values": ["30"], "negate": true }
      ]
    }
  ],
  "pageSize": 50,
  "orderBy": "lastCheckIn,asc"
}
```

Without `anyOf` and `search`, the search lists every device; with both, a device must match both.
The conditions use the same fields and operators as the REST API, listed in
[Filtering Devices](/capaone/mcp-and-api/filtering-devices/).

### Count devices per value

The versions of TeamViewer, and how many devices run each:

```json title="group_devices arguments"
{
  "field": "softwareInventory.Version",
  "anyOf": [
    { "allOf": [{ "field": "softwareInventory.Name", "operator": "EQ", "values": ["TeamViewer"] }] }
  ]
}
```

```json title="Result"
{
  "field": "softwareInventory.Version",
  "devices": 44,
  "totalGroups": 2,
  "groups": [
    { "value": "15.82.6", "devices": 41 },
    { "value": "15.69.5", "devices": 3 }
  ]
}
```

Groups come most devices first. `devices` is how many devices the filter matched. A device with
several values is in several groups, and a device without a value is in none, so the groups need
not add up to it. Without `anyOf`, `group_devices` counts every device, for example per computer
model with `hardwareInventory.Computer.Model`.

An application's name can include its version, such as "7-Zip 26.03 x64 edition", so one
application can span several groups. To count the devices that have it, filter on
`softwareInventory.Name` with `CONTAINS` "7-Zip" and read `devices`.

### Read a device

`include` picks what `get_device` returns, several sections in one call:

```json title="get_device arguments"
{ "deviceId": "65f1c0a2e4b0a1b2c3d4e5f6", "include": ["details", "security", "software_patches"] }
```

The sections are `details` (the default), `hardware`, `software`, `drivers`, `security`, `users`,
`custom`, `configurations`, `software_patches`, `driver_patches` and `custom_patches`. The result
has one key per section. A section that fails, for example a device with no driver patch data,
holds an `error` instead; the other sections still come back.

Without a category, a security, hardware or custom inventory returns its categories and how many
entries each has:

```json title="get_device arguments"
{ "deviceId": "65f1c0a2e4b0a1b2c3d4e5f6", "include": ["security"] }
```

```json title="Result"
{
  "deviceId": "65f1c0a2e4b0a1b2c3d4e5f6",
  "security": {
    "reportedAt": "2026-10-01T08:00:00Z",
    "categories": [
      { "category": "Antivirus-Summary", "entries": 1 },
      { "category": "Encryption-Summary", "entries": 1 },
      { "category": "Firewall", "entries": 3 },
      { "category": "Local Administrators-Summary", "entries": 2 },
      { "category": "Windows Update-Summary", "entries": 1 }
    ],
    "hint": "Call again with one of these categories to see its entries."
  }
}
```

Then one category, for example the device's local administrators:

```json title="get_device arguments"
{ "deviceId": "65f1c0a2e4b0a1b2c3d4e5f6", "include": ["security"], "category": "Local Administrators-Summary" }
```

The other sections are flat lists. Use `search` to find entries, for example every installed
application with "chrome" in it:

```json title="get_device arguments"
{ "deviceId": "65f1c0a2e4b0a1b2c3d4e5f6", "include": ["software"], "search": "chrome" }
```

### Read a device's custom inventory

`custom` is the data your organization's own scripts write on the device, for example its office
location. It isn't `custom_patches`, the custom applications assigned to the device. Like a hardware
inventory, `custom` returns its categories first. Each entry in a category is one instance, named
by its `Instance`:

```json title="get_device arguments"
{ "deviceId": "65f1c0a2e4b0a1b2c3d4e5f6", "include": ["custom"], "category": "Office" }
```

```json title="Result"
{
  "deviceId": "65f1c0a2e4b0a1b2c3d4e5f6",
  "custom": {
    "reportedAt": "2026-10-01T08:00:00Z",
    "category": "Office",
    "total": 1,
    "returned": 1,
    "rows": [
      {
        "Instance": "default",
        "City": "Copenhagen",
        "Floor": 3,
        "Last Updated": { "value": "2026-09-30T12:00:00.000Z", "unit": "date" }
      }
    ]
  }
}
```

A value with a unit, such as a date or a size, comes as its `value` and `unit`. A device that has
never reported custom inventory holds an `error` for `custom`. To find devices by their custom inventory, see
[Filtering Devices](/capaone/mcp-and-api/filtering-devices/#custom-inventory-fields).