# Troubleshooting & FAQ

> Diagnose connection, authentication, and data issues, plus answers to common questions and MCP limits.

## Troubleshooting

### The assistant can’t reach VisualOne

Run a health check (`visualone_health_check`). If `mongoConnection` is `OK`, the API and datastore are healthy and the problem is elsewhere (authentication or the specific request). Anything other than `OK`, or no response, means the Arbiter API or its datastore is unavailable — a backend issue; contact your VOI administrator.

### Calls fail with an authentication error

Check your session (`visualone_get_session`). If `status` is not `authenticated`, reconnect the `VisualOneMCP` server in your client (in Claude Code, run `/mcp`). If `expiresAt` is in the past, your token has expired — re-authenticate.

### You don’t know the exact name for a drilldown

Don’t guess. Use `visualone_list_units` with the `search` parameter to resolve it by partial name (for example `{ "unit_type": "devices", "search": "dal" }`).

### list_units results look truncated

The response includes `total_matching`. If it exceeds the rows returned, add filters (e.g. `vcenter_name`, `cluster_name`) or a more specific `search` term rather than raising `limit`. A narrower query is faster and cheaper.

### A report returns no data

- The report may have no data for the resolved period. Try passing an explicit `period_id`, or confirm data collection is current in the VOI app.
- A drilldown report needs its `navigation` parameter. Re-check discovery to see which identifiers the report requires.

### The numbers look wrong for the timeframe

`period_id` defaults to the **latest** period for the report’s context. If you need a different snapshot, pass `period_id` explicitly.

## FAQ

**Can the MCP change anything in VOI?**
No. All five tools are read-only. They retrieve and format data; nothing creates, edits, or deletes.

**Do I need to know report names or IDs?**
No. Describe what you want in plain language; `visualone_discover_reports` finds the right report and tells the assistant how to run it.

**Do I have to provide client_id or period_id?**
No. Both are resolved automatically from your session and the report’s context. Supply them only to override (and `client_id` overrides are limited to super users).

**What’s the difference between Markdown and JSON output?**
Markdown (the default) is formatted for reading in chat. JSON is structured data for computing on, charting, or exporting. Set `response_format` accordingly.

**Which reports need extra parameters?**
Enterprise / summary reports usually need none. Drilldown reports need a `navigation` identifier (device, vCenter, cluster, host, VM, switch, or instance name). Discovery shows each report’s parameters and their source.

**Can I report on a different client/tenant?**
Only if your `role` is `super_user`, by passing `client_id` to `visualone_get_reports`. Standard users are scoped to their own client.

**Is the data live?**
Yes — reports run against your current VOI data for the resolved period. Treat output as production data and anonymize before publishing it anywhere public.

**Can I list every available report at once?**
There is no “list all” call — the catalog is reached through search. Use broad or repeated `visualone_discover_reports` queries (raising `limit` up to 20) across topics, or look up a known report directly with `report_id`.

## Limits at a glance

| Limit | Value |
| --- | --- |
| `discover_reports` results per call | default 5, max 20 |
| `list_units` rows per call | default 100, max 500 |
| Write operations | none — read-only |
| Tenant scope | your session’s client (super users may override) |
| Default period | latest period for the report’s context |

---

Source: https://visualoneintelligence.com/docs/voi-mcp-troubleshooting/