MCP Tools

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.

How an agent uses them

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

Asked which organization it is connected to, it calls get_organization.
Before filtering, it calls list_filterable_fields once. Then search_devices finds and counts devices, and group_devices counts them per value.
For exact filter values, such as computer models or application names, it calls group_devices.
For one device, it takes the id from the search and calls get_device with the sections it needs, get_events or get_elevations.
For a hardware, security or custom inventory, get_device returns the overview of categories first. The agent then asks for the category it needs.
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.
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.
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:

{
  "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.

Count devices per value

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

{
  "field": "softwareInventory.Version",
  "anyOf": [
    { "allOf": [{ "field": "softwareInventory.Name", "operator": "EQ", "values": ["TeamViewer"] }] }
  ]
}

{
  "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:

{ "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:

{ "deviceId": "65f1c0a2e4b0a1b2c3d4e5f6", "include": ["security"] }

{
  "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:

{ "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:

{ "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:

{ "deviceId": "65f1c0a2e4b0a1b2c3d4e5f6", "include": ["custom"], "category": "Office" }

{
  "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.