# Core Concepts

> Contexts, periods, client scope, parameter sources, and the drilldown model behind the VisualOne MCP.

Understanding a handful of concepts makes the VisualOne MCP predictable and easy to use. Most of them mirror how the VOI application itself is organized.

## The report registry

Everything the MCP can run is described in a **report registry**. Each entry describes one report:

| Field | Meaning |
| --- | --- |
| `reportId` | Stable identifier, e.g. `storage-enterprise-capacity-plan` |
| `title` | Human-readable name, e.g. Enterprise Capacity Plan |
| `context` | The area / navigation level the report belongs to |
| `tags` | Keywords used for search |
| `apiRoutes` | One or more stored procedures (`proc_name`) that produce the report, each with its parameter list |
| `howToRun` | A ready-to-use call template, including which parameters are auto-resolved |

You rarely read the registry directly — you search it with `visualone_discover_reports`, which returns these fields plus a `howToRun` block telling you how to execute the report.

## Contexts

A **context** is the level of the environment a report describes. It maps to the VOI application’s navigation hierarchy — from enterprise-wide rollups down to a single device or VM. Contexts include: ENTERPRISE, STORAGE, DEVICE, HOSTS, SAN-SWITCH, SWITCH, VIRTUAL, DATA CENTER, ESX HOST, DATABASE, SERVER, KUBERNETES, CLOUD, FINOPS, BACKUP, and BUSINESS UNIT.

Contexts group related reports, and the correct reporting **period** is resolved per-context.

## Periods

VOI collects data in **periods** (reporting snapshots). Every report needs a `period_id`, but you almost never supply it: the MCP automatically resolves the **latest period for your client** based on the report’s context. Pass `period_id` explicitly only to override.

## Client (tenant) context

Every call runs against a single **client** (`client_id`), resolved automatically from your authenticated session. Standard users are locked to their own client; there is no need to pass `client_id` in normal use.

## Parameter sources

Every report parameter declares a **source** that tells you where its value comes from — the key to knowing what (if anything) you must provide:

| Source | Who supplies it | Example |
| --- | --- | --- |
| `context` | Auto-resolved from your session / period. Do not ask for it. | `client_id`, `period_id` |
| `navigation` | A drilldown identifier — the specific entity you are inspecting. You must supply it. | `device_name`, `vcenter_name` |
| `user_input` | An optional filter to narrow results. | `unit`, `resource_type`, `tag_key` |

In practice: if a report only has `context` parameters, you can run it immediately. If it has `navigation` parameters, you first need the exact entity name — which is what `visualone_list_units` is for.

## Drilldowns and the navigation model

VOI reports form a hierarchy. Enterprise-level reports summarize everything; drilldown reports zoom into one entity and require that entity’s exact name as a `navigation` parameter. A common virtualization chain:

```
Enterprise summary
   └─ vCenter (vcenter_name)
        └─ Cluster (cluster_name)
             └─ ESX host (esx_host_name)
                  └─ VM (vm_name) / Datastore (datastore_name)
```

To move down this chain you resolve names progressively with `visualone_list_units`: list vCenters, then clusters filtered by vCenter, then ESX hosts filtered by cluster, and so on.

## Response formats

- **markdown** (default) — clean tables and headings, ideal for reading in chat.
- **json** — structured data, ideal when the assistant needs to compute on, chart, or export the results.

## Roles and permissions

- **standard_user** — all calls run against your own client. `client_id` is resolved from your session and cannot be changed.
- **super_user** — may pass `client_id` explicitly to `visualone_get_reports` to query on behalf of another client. When omitted, the session client is used.

Regardless of role, the MCP is **read-only** — no tool modifies VOI data.

## Stored procedures

Reports are backed by named stored procedures (for example `enterprise_capacity_plan_proc`). A single report may expose several — for instance a “Storage by Group” report offers routes grouped by data center, device type, tier, and so on. You choose the grouping by picking the matching `proc_name` returned from discovery.

---

Source: https://visualoneintelligence.com/docs/voi-mcp-core-concepts/