Connect NuraVolt to Claude, ChatGPT, or Cursor.
Three real steps. If everything is in place, ten minutes end-to-end. This page is also the technical reference — scopes, rate limits, idempotency, troubleshooting.
Prerequisites
- A NuraVolt organisation. If you haven't signed up yet, book a demo — we onboard your plants first.
- Admin role in the org. Only admins can mint MCP API keys. Contact your NuraVolt admin if you don't have this.
- An MCP-aware client. Claude Desktop (Nov 2025 or later), ChatGPT Business / Enterprise, Cursor, or Continue.dev. Anything speaking the current MCP HTTP-streaming spec works.
Generate a scoped key
- Open Settings › MCP API keys in the dashboard.
- Click Generate key.
- Give the key a name that identifies the human or app using it (e.g. Claude Desktop — Anna). This name only shows in your dashboard.
- Pick scopes. Start with Read-only preset for a first connection, upgrade to Full agent preset when you're ready to let the AI create tickets and cleaning schedules.
- Copy the raw token — nv_live_… — the reveal dialog shows once and never again.
Install the connector
{
"mcpServers": {
"nuravolt": {
"url": "https://nuravolt.com/api/mcp/mcp",
"headers": {
"Authorization": "Bearer nv_live_YOUR_KEY_HERE"
}
}
}
}Verify it works
Restart your client. In a new conversation, ask it:
“Using the NuraVolt connector, list my plants.”
The assistant should call nuravolt_list_plants and return your real plants. If it does, connectivity + auth + scopes are all good.
You can also confirm in the dashboard — the call should show up in the Recent tool calls audit panel within seconds.
Scopes
Ten fine-grained scopes. Every tool declares exactly which scope it needs; a key without that scope gets a forbidden error with the specific missing scope named.
| Scope | What it grants |
|---|---|
| plants:read | List and view plant metadata. |
| inverters:read | List and view inverters at a plant. |
| soiling:read | Query soiling forecasts and recovery windows. |
| bess:read | Query BESS revenue and ancillary services data. |
| faults:read | Deterministic rule-based fault classifier. |
| tickets:read | List and view maintenance tickets. |
| kb:read | Semantic search over uploaded knowledge base. |
| diagnosis:run | Run AI diagnosis on an inverter (paid inference). |
| tickets:write | Create tickets, transition status, add comments. |
| cleaning:write | Persist a cleaning schedule with ROI economics. |
Tools
Every tool the MCP server exposes. All schemas are Zod-validated on the server — malformed args get rejected with a structured error.
| Tool | Purpose | Scope |
|---|---|---|
| nuravolt_list_plants | List every plant this key can see, with asset type, capacity, and location. | plants:read |
| nuravolt_list_inverters | List inverters at a plant, with model and rated capacity. | inverters:read |
| nuravolt_get_soiling_forecast | 365-day soiling ratio forecast, confidence bounds, cleaning recommendations. | soiling:read |
| nuravolt_get_inverter_classification | Rule-based diagnosis for one inverter — cause, confidence, ETA, recommended action. | faults:read |
| nuravolt_diagnose_inverter | Bedrock-backed 30-day digital-twin analysis. Severity, fault hypothesis, actions. | diagnosis:run |
| nuravolt_get_bess_revenue | Ancillary services + wholesale revenue breakdown for a BESS plant. | bess:read |
| nuravolt_list_tickets | Maintenance tickets with filters — plant, status, priority, limit. | tickets:read |
| nuravolt_search_knowledge_base | Semantic search over uploaded manuals, datasheets, runbooks, incident reports. | kb:read |
| nuravolt_create_ticketwrite | Create a maintenance ticket (status NEW). Idempotency key required. | tickets:write |
| nuravolt_update_ticket_statuswrite | Move a ticket forward: NEW → VALIDATED → ASSIGNED → IN_PROGRESS → DONE. | tickets:write |
| nuravolt_comment_on_ticketwrite | Add a comment. Attributed to the API key so the timeline shows the AI source. | tickets:write |
| nuravolt_approve_cleaning_schedulewrite | Persist a cleaning schedule with dates + economics. Auto-computes ROI + payback. | cleaning:write |
Rate limits, idempotency, audit
Rate limits
60 requests per minute and 5,000 per day per key, per plan tier. Bursts over the limit return a structured rate_limited error with retry_after_sec. Well-behaved clients back off automatically.
Idempotency
Every write tool takes an idempotency_key. Retries with the same key + tool return the original result, no duplicate row. Use a stable key per logical action (e.g. a UUID your agent generates once per user intent).
Audit
Every call — read, write, forbidden, rate-limited — writes an audit row with duration, args, status, and (for writes) the row it created. Visible in the dashboard's Recent tool calls panel and queryable via the admin API.
Troubleshooting
HTTP 401 on every callBearer token is missing, malformed, or the key has been revoked. Copy the token again from the reveal dialog if you still have it; otherwise revoke and regenerate.
forbidden: Missing required scope: <scope>The key doesn't grant that scope. In Settings → MCP API keys, revoke the current key and generate a new one with the required scope ticked.
rate_limited: minute_limitYour client is bursting. Wait retry_after_sec seconds, then retry. If you need higher throughput sustainably, talk to us about plan tiers.
invalid_transition: NEW → DONETickets must move through the workflow — you can only jump from NEW to VALIDATED or WONT_FIX. Read the allowed-transitions map in the tool schema.
Tool doesn't appear in the assistantRestart the client fully. In Claude Desktop, use ⌘Q to quit, not just close the window. In Cursor, toggle NuraVolt off and on in Settings → MCP.