auvik-api-patterns

Auvik MCP Tools and API Patterns

Overview

The Auvik MCP server wraps the Auvik REST API (https://auvikapi.{region}.my.auvik.com/v1 and /v2) and exposes tools across tenants, devices, networks, interfaces, configurations, alerts, statistics, and billing. Two quirks to know up front: Auvik uses HTTP Basic auth with username:apiKey (not a bearer token), and the API base URL is region-pinned - your credentials only work against the cluster your tenant lives in.

Authentication

Auvik authenticates with HTTP Basic - the username is the Auvik user's email and the password is the API key.

Field	Value
Auth scheme	HTTP Basic
Username	AUVIK_USERNAME (your Auvik login email)
Password	AUVIK_API_KEY

The MCP server handles the basic-auth encoding. Set the env vars; do not pre-encode.

Region Routing

Auvik tenants live in one of several regional clusters:

Region	Base host
us1	auvikapi.us1.my.auvik.com
us2	auvikapi.us2.my.auvik.com
us3	auvikapi.us3.my.auvik.com
us4	auvikapi.us4.my.auvik.com
eu1	auvikapi.eu1.my.auvik.com
eu2	auvikapi.eu2.my.auvik.com
au1	auvikapi.au1.my.auvik.com
ca1	auvikapi.ca1.my.auvik.com

Set AUVIK_REGION to pin the region. If omitted, the server attempts to detect the region from the credentials. Misroutes typically surface as 404 or redirect loops on calls that should obviously succeed.

JSON:API Envelope

Auvik returns JSON:API-shaped responses. The tools surface this through to users, so know the shape:

{
  "data": [
    {
      "id": "...",
      "type": "device",
      "attributes": { ... },
      "relationships": { ... }
    }
  ],
  "links": { "next": "...", "prev": "...", "first": "...", "last": "..." },
  "meta": { "totalRecords": 1284, "totalPages": 26 },
  "included": [ ... ]
}

Key points:

• The record's real fields live under attributes, not the top level.
• Relationships to other entities are referenced under relationships, not embedded - use included (when present) for sideloads.
• Use links.next for the next page rather than constructing the URL yourself.

Singletons (*_get style tools) return data as an object, not an array.

Pagination

Auvik uses cursor-style pagination via links.next. Pattern:

1. Call the list tool. Read data and links.next.
2. If links.next is non-null, the tool exposes a way to fetch the next page (usually a page_first / page_after argument that the MCP server populates from the cursor).
3. Continue until links.next is null or your accumulated count reaches a sane cap.

Use page sizes of 100-500. Larger pages can time out on big tenants.

meta.totalRecords is the authoritative count - prefer it over counting accumulated rows when reporting size.

Rate Limits

Auvik enforces per-API-key rate limits. Behavior at limit:

• 429 status with a Retry-After header.
• The MCP server surfaces this as a tool error. Back off, then retry.
• If you're hitting limits routinely, narrow the query (one tenant at a time, smaller windows) rather than tightening the retry loop.

Statistics endpoints (auvik_statistics_*) are noticeably heavier than entity listings - rate-limit pressure usually shows up there first when scanning a large tenant.

v1 vs v2 Device API

Auvik exposes two generations of device endpoints. The MCP tools split them:

Tool	API
auvik_devices_list, auvik_devices_get	v1 - light record, fast
auvik_devices_get_details	v2 - extended attributes
auvik_devices_get_lifecycle	v2 - lifecycle fields
auvik_devices_get_warranty	v2 - warranty fields

Default to v1 for bulk listings; reach for v2 only when you need the extended fields. Calling v2 tools in a tight loop over a large device set is the single most common cause of rate-limit problems.

Multi-Tenant Routing

Auvik is multi-tenant by design - a single MSP credential sees every client tenant the MSP manages. Pattern:

1. auvik_tenants_list to enumerate visible tenants.
2. Filter and pass the chosen tenant_id (or tenantId, depending on the tool) on subsequent calls.
3. For fleet-wide reports, fan out across tenants client-side rather than expecting a single call to roll them up.

Error Handling

Code	Meaning	Fix
401	Bad credentials	Check AUVIK_USERNAME + AUVIK_API_KEY
403	Credentials valid, no access to the resource	Wrong tenant, or key lacks scope
404	Unknown ID, or wrong region	Verify region; verify ID
429	Rate limit	Back off; narrow the query
500	Auvik-side hiccup	Retry, then escalate

Best Practices

• Always pass tenant_id explicitly on per-tenant reports - implicit scoping is a source of cross-tenant data leaks in human-facing output.
• Default to v1 device endpoints; promote to v2 only for the device subset that needs it.
• For statistics queries, prefer short windows (24h) for interactive use and reserve longer windows (7d / 30d) for batch capacity reports.
• Cache auvik_tenants_list results within a session - the tenant list rarely changes.

Related Skills

• devices
• alerts
• networks