Troubleshooting & FAQ

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