unraid-mcp/docs/research/unraid-api-research.md

# Unraid API Research Findings

**Date:** 2026-02-07
**Research Topic:** Unraid GraphQL API, Connect Cloud Service, MCP Integration
**Specialist:** NotebookLM Deep Research
**Notebook ID:** 4e217d5d-d68b-4bfa-881a-42f7c01d3e44

## Research Summary

- **Deep research mode:** deep (47 web sources discovered)
- **Sources indexed:** 51 ready / 77 total (26 error)
- **Q&A questions asked:** 23 comprehensive questions with follow-ups
- **Deep research status:** completed
- **Key source categories:** Official Unraid docs, GitHub repos, community forums, GraphQL references, third-party integrations

---

## Table of Contents

1. [Unraid API Overview](#1-unraid-api-overview)
2. [Architecture and Deployment](#2-architecture-and-deployment)
3. [Authentication and Security](#3-authentication-and-security)
4. [GraphQL Schema and Endpoints](#4-graphql-schema-and-endpoints)
5. [WebSocket Subscriptions](#5-websocket-subscriptions)
6. [Unraid Connect Cloud Service](#6-unraid-connect-cloud-service)
7. [Version History and API Changes](#7-version-history-and-api-changes)
8. [Community Integrations](#8-community-integrations)
9. [Known Issues and Limitations](#9-known-issues-and-limitations)
10. [API Roadmap and Future Features](#10-api-roadmap-and-future-features)
11. [Recommendations for unraid-mcp](#11-recommendations-for-unraid-mcp)
12. [Source Bibliography](#12-source-bibliography)

---

## 1. Unraid API Overview

The **Unraid API** is a programmatic interface that provides automation, monitoring, and integration capabilities for Unraid servers. It uses a **GraphQL** interface, offering a modern, strongly-typed method for developers and third-party applications to interact directly with the Unraid operating system.

### Key Facts

- **Protocol:** GraphQL (queries, mutations, subscriptions)
- **Endpoint:** `http(s)://[SERVER_IP]/graphql`
- **Authentication:** API Keys, Session Cookies, SSO/OIDC
- **Native since:** Unraid 7.2 (no plugin required)
- **Pre-7.2:** Requires Unraid Connect plugin installation

The API exposes nearly all management functions available in the Unraid WebGUI, including server management, storage operations, Docker/VM lifecycle, remote access, and backup capabilities.

**Sources:**
- [Welcome to Unraid API | Unraid Docs](https://docs.unraid.net/API/) -- Official API landing page [Tier: Primary]
- [Using the Unraid API](https://docs.unraid.net/API/how-to-use-the-api/) -- Official usage guide [Tier: Primary]

---

## 2. Architecture and Deployment

### Monorepo Structure

The Unraid API is developed in the [unraid/api](https://github.com/unraid/api) monorepo which houses:

| Directory | Purpose |
|-----------|---------|
| `api/` | GraphQL backend server (TypeScript/Node.js) |
| `web/` | Frontend interface (Nuxt/Vue.js) |
| `plugin/` | Unraid plugin packaging (.plg format) |
| `packages/` | Shared internal libraries |
| `unraid-ui/` | UI component library |
| `scripts/` | Build and maintenance utilities |

### Technology Stack

| Component | Technology |
|-----------|------------|
| Primary language | TypeScript (77.4%) |
| Frontend | Vue.js (11.8%) via Nuxt |
| Runtime | Node.js v22 |
| Package manager | pnpm v9.0+ |
| API protocol | GraphQL |
| Dev environment | Nix (optional), Docker |
| Build tool | Justfile |

### Deployment Modes

1. **Native (Unraid 7.2+):** API is built into the OS, starts automatically with the system. Managed via **Settings > Management Access > API**.
2. **Plugin (Pre-7.2):** Requires installing the Unraid Connect plugin from Community Applications. Installing the plugin on 7.2+ provides access to newer API features before they are merged into the stable OS release.
3. **Development:** Supports local Docker builds (`pnpm run docker:build-and-run` on port 5858), direct deployment to a running server (`pnpm unraid:deploy <SERVER_IP>`), and hot-reloading dev servers (API port 3001, Web port 3000).

### Integration with Nginx

The API integrates with Unraid's Nginx web server. Nginx acts as a reverse proxy, handling external requests on standard web ports (80/443) and routing `/graphql` traffic to the internal API backend. This means the API shares the same IP and port as the WebGUI.

**Sources:**
- [GitHub - unraid/api: Unraid API / Connect / UI Monorepo](https://github.com/unraid/api) [Tier: Official]
- [api/api/docs/developer/development.md](https://github.com/unraid/api/blob/main/api/docs/developer/development.md) [Tier: Official]

---

## 3. Authentication and Security

### Authentication Methods

The Unraid API supports three primary authentication mechanisms:

1. **API Keys** -- Standard method for programmatic access
   - Created via WebGUI: **Settings > Management Access > API Keys**
   - Created via CLI: `unraid-api apikey --create --name "mykey" --roles ADMIN --json`
   - Sent in HTTP header: `x-api-key: YOUR_API_KEY`
   - Displayed only once upon creation

2. **Session Cookies** -- Used for browser-based WebGUI access
   - Automatic when logged into WebGUI
   - Used internally by the GraphQL Sandbox

3. **SSO / OIDC (OpenID Connect)** -- Enterprise identity management
   - Added in API v4.0.0
   - Supports external identity providers

### API Key Authorization Flow (OAuth-like)

For third-party applications, Unraid provides an OAuth-like authorization flow:

1. App redirects user to: `https://[server]/ApiKeyAuthorize?name=MyApp&scopes=docker:read,vm:*&redirect_uri=https://myapp.com/callback&state=abc123`
2. User authenticates (if not already logged in)
3. User sees consent screen with requested permissions
4. Upon approval, API key is created and shown to user once
5. If `redirect_uri` provided, user is redirected with `?api_key=xxx&state=abc123`

**Query Parameters:**
| Parameter | Required | Description |
|-----------|----------|-------------|
| `name` | Yes | Application name |
| `scopes` | Yes | Comma-separated permissions (e.g., `docker:read,vm:*`) |
| `redirect_uri` | No | HTTPS callback URL (localhost allowed for dev) |
| `state` | No | CSRF prevention token |

### Programmatic API Key Management (CLI)

```bash
# Create a key with admin role
unraid-api apikey --create --name "workflow key" --roles ADMIN --json

# Create a key with specific permissions
unraid-api apikey --create --name "monitor" --permissions "DOCKER:READ_ANY,ARRAY:READ_ANY" --json

# Overwrite existing key
unraid-api apikey --create --name "workflow key" --roles ADMIN --overwrite --json

# Delete a key
unraid-api apikey --delete --name "workflow key"
```

### Roles and Permissions

**Roles (pre-defined access levels):**

| Role | Description |
|------|-------------|
| `ADMIN` | Full system access (all permissions) |
| `VIEWER` | Read-only access |
| `GUEST` | Limited access |
| `CONNECT` | Unraid Connect cloud features |

**Permission Scope Format:** `RESOURCE:ACTION`

**Available Resources:**
- Core: `ACTIVATION_CODE`, `API_KEY`, `CONFIG`, `CUSTOMIZATIONS`, `INFO`, `LOGS`, `OS`, `REGISTRATION`, `VARS`, `WELCOME`
- Storage: `ARRAY`, `DISK`, `FLASH`
- Services: `DOCKER`, `VMS`, `SERVICES`, `NETWORK`
- Management: `DASHBOARD`, `DISPLAY`, `ME`, `NOTIFICATIONS`, `OWNER`, `PERMISSION`, `SHARE`, `USER`
- Cloud: `CLOUD`, `CONNECT`, `CONNECT__REMOTE_ACCESS`, `ONLINE`, `SERVERS`

**Available Actions:**
- `CREATE_ANY`, `CREATE_OWN`
- `READ_ANY`, `READ_OWN`
- `UPDATE_ANY`, `UPDATE_OWN`
- `DELETE_ANY`, `DELETE_OWN`
- `*` (wildcard for all actions)

### SSL/TLS Certificate Handling

| Scenario | Recommendation |
|----------|---------------|
| Self-signed cert (local IP) | Either trust the specific CA or disable SSL verification (dev only) |
| `myunraid.net` cert (Let's Encrypt) | SSL verification works normally; use the `myunraid.net` URL |
| Strict SSL mode | Enforces HTTPS for all connections including local |

For self-signed certs in client code:
```bash
curl -k "https://your-unraid-server/graphql" -H "x-api-key: YOUR_KEY"
```

**Sources:**
- [API key authorization flow | Unraid Docs](https://docs.unraid.net/API/api-key-app-developer-authorization-flow/) [Tier: Primary]
- [Programmatic API key management | Unraid Docs](https://docs.unraid.net/API/programmatic-api-key-management/) [Tier: Primary]

---

## 4. GraphQL Schema and Endpoints

### Endpoint URLs

| Purpose | URL |
|---------|-----|
| GraphQL API | `http(s)://[SERVER_IP]/graphql` |
| GraphQL Sandbox | `http(s)://[SERVER_IP]/graphql` (must be enabled) |
| WebSocket (subscriptions) | `ws(s)://[SERVER_IP]/graphql` |
| Internal dev API | `http://localhost:3001/graphql` |

### Enabling the GraphQL Sandbox

Two methods:
1. **WebGUI:** Settings > Management Access > Developer Options > Toggle GraphQL Sandbox to "On"
2. **CLI:** `unraid-api developer --sandbox true`

Then access at `http://YOUR_SERVER_IP/graphql` to explore the schema via Apollo Sandbox.

### Query Types

#### System Information (`info`)
```graphql
query {
  info {
    os { platform distro release uptime hostname arch kernel }
    cpu { manufacturer brand cores threads }
    memory { layout { bank type clockSpeed manufacturer } }
    baseboard { manufacturer model version serial }
    system { manufacturer model version serial uuid }
    versions { kernel docker unraid node }
    apps { installed started }
    machineId
    time
  }
}
```

#### Array Status (`array`)
```graphql
query {
  array {
    id
    state
    capacity {
      kilobytes { free used total }
      disks { free used total }
    }
    boot { id name device size status temp fsType }
    parities { id name device size status temp numErrors }
    disks { id name device size status temp numReads numWrites numErrors }
    caches { id name device size status temp }
  }
}
```

#### Docker Containers (`docker`)
```graphql
query {
  docker {
    containers(skipCache: false) {
      id names image state status autoStart
      ports { ip privatePort publicPort type }
      labels
      networkSettings
      mounts
    }
  }
}
```

#### Virtual Machines (`vms`)
```graphql
query {
  vms {
    id
    domains {
      id name state uuid
    }
  }
}
```

#### Network (`network`)
```graphql
query {
  network {
    id
    accessUrls { type name ipv4 ipv6 }
  }
}
```

#### Registration (`registration`)
```graphql
query {
  registration {
    id type state expiration updateExpiration
    keyFile { location contents }
  }
}
```

#### Settings (`settings`)
```graphql
query {
  settings {
    unified { values }
  }
}
```

#### System Variables (`vars`)
```graphql
query {
  vars {
    id version name timeZone security workgroup
    useSsl port portssl
    shareSmbEnabled shareNfsEnabled
    mdState mdVersion
    csrfToken
    # Many more fields available -- some have Int overflow issues
  }
}
```

#### RClone Remotes (`rclone`)

```graphql
query {
  rclone {
    remotes { name type parameters config }
    configForm(formOptions: { providerType: "s3" }) {
      id dataSchema uiSchema
    }
  }
}
```

#### Notifications

```graphql
query {
  notifications {
    id subject message importance unread
  }
}
```

#### Shares

```graphql
query {
  shares {
    name comment free used
  }
}
```

### Mutation Types

#### Docker Container Management

```graphql
mutation {
  docker {
    start(id: $id) { id names state status }
    stop(id: $id) { id names state status }
  }
}
```
- Uses `PrefixedID` type for container identification
- Mutations are idempotent (starting an already-running container returns success)

#### VM Management

```graphql
mutation {
  vm {
    start(id: $id)    # Returns Boolean
    stop(id: $id)
    pause(id: $id)
    resume(id: $id)
    forceStop(id: $id)
    reboot(id: $id)
    reset(id: $id)
  }
}
```

#### RClone Remote Management
```graphql
mutation {
  rclone {
    createRCloneRemote(input: { name: "...", type: "s3", config: {...} }) {
      name type parameters
    }
    deleteRCloneRemote(input: { name: "..." })
  }
}
```

#### System Operations (via API)
The following operations are confirmed available through the API (exact mutation names should be discovered via introspection):
- Array start/stop
- Parity check trigger
- Server reboot/shutdown
- Flash backup trigger
- Notification management

### The `PrefixedID` Type

The API uses a `PrefixedID` custom scalar type for global object identification. This follows the GraphQL `Node` interface pattern, combining the object type and its internal ID (e.g., `DockerContainer:abc123`). Client libraries must handle this as a string.

### The `Long` Scalar Type

The API defines a custom `Long` scalar type for 64-bit integers to handle values that exceed the standard GraphQL `Int` (32-bit signed). This is used for:
- Disk/array capacity values (size, free, used, total)
- Memory values (total, free)
- Disk operation counters (numReads, numWrites)

These are typically serialized as strings in JSON responses.

**Sources:**
- [Welcome to Unraid API | Unraid Docs](https://docs.unraid.net/API/) [Tier: Primary]
- [Using the Unraid API](https://docs.unraid.net/API/how-to-use-the-api/) [Tier: Primary]
- [GitHub - jmagar/unraid-mcp](https://github.com/jmagar/unraid-mcp) [Tier: Official]

---

## 5. WebSocket Subscriptions

### Protocol

The Unraid API uses the **`graphql-transport-ws`** protocol (the modern standard, superseding the older `subscriptions-transport-ws`).

### Connection Flow

1. Client connects to `ws(s)://[SERVER_IP]/graphql`
2. Client sends `connection_init` with auth payload:
   ```json
   {
     "type": "connection_init",
     "payload": {
       "x-api-key": "YOUR_API_KEY"
     }
   }
   ```
3. Server responds with `connection_ack`
4. Client sends `subscribe` message with GraphQL subscription query
5. Server streams `next` messages with data as events occur
6. Server sends `complete` when subscription ends

### Known Subscription Types

| Subscription | Purpose |
|-------------|---------|
| `syslog` / `logFile` | Real-time system log streaming |
| Array events | State changes, parity check progress |
| Docker events | Container state changes |
| Notifications | Real-time alert streaming |

### Authentication for WebSockets

Since standard WebSocket APIs in browsers cannot set custom headers, the API key is passed in the `connectionParams` payload of the `connection_init` message. Alternatively, session cookies work automatically for WebGUI-based tools.

### Infrastructure Notes

- Unraid uses **Nchan** (Nginx module) for WebSocket connections internally
- Unraid 7.0.1 fixed Nchan memory leaks affecting subscription stability
- Unraid 7.1.0 added automatic Nchan shared memory recovery (restarts Nginx when memory runs out)
- A setting was added in 7.1.0 to disable real-time updates on inactive browsers to prevent memory issues

**Sources:**
- [Subscriptions - GraphQL](https://graphql.org/learn/subscriptions/) [Tier: Primary]
- [Subscriptions - Apollo GraphQL Docs](https://www.apollographql.com/docs/react/data/subscriptions) [Tier: Official]

---

## 6. Unraid Connect Cloud Service

### Overview

**Unraid Connect** is a cloud-enabled companion service that functions as a centralized "remote command center" for Unraid servers. It provides:

- **Centralized Dashboard:** View status, uptime, storage, and license details for multiple servers
- **Remote Management:** Start/stop arrays, manage Docker/VMs, reboot servers
- **Flash Backup:** Automated cloud-based backups of USB flash drive configuration
- **Deep Linking:** Jump directly from cloud dashboard to local WebGUI pages

### Relationship to Local API

- Pre-7.2: The Unraid Connect plugin provides both cloud features AND the local GraphQL API
- Post-7.2: The API is native to the OS; the Connect plugin adds cloud features
- The cloud dashboard communicates through a secure tunnel to execute commands locally

### Data Transmitted to Cloud

The local server transmits to `Unraid.net`:
- Server hostname and keyfile details
- Local/remote IP addresses
- Array usage statistics (numbers only, no file names)
- Container and VM counts

**Privacy:** The service explicitly does NOT collect or share user content, file details, or personal information beyond necessary metadata.

### Remote Access Mechanisms

1. **Dynamic Remote Access (Recommended):**
   - On-demand; WebGUI closed to internet by default
   - Uses UPnP for automatic port forwarding (or manual rules)
   - Port lease expires after inactivity (~10 minutes)

2. **Static Remote Access:**
   - Always-on; WebGUI continuously accessible
   - Requires forwarding WAN port (high random number >1000) to HTTPS port

3. **VPN Alternatives:**
   - WireGuard (built-in)
   - Tailscale (native since Unraid 7.0+)

### Flash Backup Details

- Configuration files are encrypted and uploaded
- Excludes sensitive data: passwords, WireGuard keys
- Retained as latest backup only; older/inactive backups are purged
- Can be triggered and monitored via the API

**Sources:**
- [Unraid Connect overview & setup | Unraid Docs](https://docs.unraid.net/connect/about/) [Tier: Primary]
- [Remote access | Unraid Docs](https://docs.unraid.net/connect/remote-access/) [Tier: Primary]
- [Automated flash backup | Unraid Docs](https://docs.unraid.net/connect/flash-backup/) [Tier: Primary]

---

## 7. Version History and API Changes

### Unraid 7.0.0 (2025-01-09)

**Developer & System Capabilities:**
- Notification agents stored as individual XML files (easier programmatic management)
- `Content-Security-Policy frame-ancestors` support (iframe embedding for dashboards)
- JavaScript console logging restored
- VM Manager inline XML mode (read-only libvirt XML view)
- Docker PID limits (default 2048)
- Full ZFS support (hybrid pools, subpools, encryption)
- Native Tailscale integration
- File Manager merged into core OS
- QEMU snapshots and clones for VMs

**Note:** API was still plugin-based (Unraid Connect plugin required).

### Unraid 7.0.1 (2025-02-25)

- **Nchan memory leak fix** -- Critical for WebSocket subscription stability
- Tailscale integration security restrictions for Host-network containers

### Unraid 7.1.0 (2025-05-05)

- **Nchan shared memory recovery** -- Automatic Nginx restart on memory exhaustion
- **Real-time updates toggle** -- Disable updates on inactive browsers
- Native WiFi support (`wlan0`) -- New network interface data
- User VM templates (create, export, import)
- CSS rework for WebGUI

### Unraid 7.2.0 (Stable Release)

**Major Milestone: API becomes native to the OS.**

- No plugin required for local API access
- API starts automatically with system
- Deep system integration
- Settings accessible at **Settings > Management Access > API**
- OIDC/SSO support added
- Permissions system rewritten (API v4.0.0)
- Built-in GraphQL Sandbox
- CLI key management (`unraid-api apikey`)
- Open-sourced API code

**Sources:**
- [Version 7.0.0 | Unraid Docs](https://docs.unraid.net/unraid-os/release-notes/7.0.0/) [Tier: Primary]
- [Version 7.0.1 | Unraid Docs](https://docs.unraid.net/unraid-os/release-notes/7.0.1/) [Tier: Primary]
- [Version 7.1.0 | Unraid Docs](https://docs.unraid.net/unraid-os/release-notes/7.1.0/) [Tier: Primary]
- [Unraid 7.2.0 Blog Post](https://unraid.net/blog/unraid-7-2-0) [Tier: Official]

---

## 8. Community Integrations

### Third-Party Projects Using the Unraid API

#### 1. unraid-mcp (Python MCP Server) -- This Project
- **Interface:** Official Unraid GraphQL API via HTTP/HTTPS + WebSockets
- **Auth:** `UNRAID_API_URL` + `UNRAID_API_KEY` environment variables
- **Transport:** HTTP header `X-API-Key` for queries; WebSocket `connection_init` payload for subscriptions
- **Tools:** 26+ MCP tools for Docker, VM, storage, system management

#### 2. PSUnraid (PowerShell Module)
- **Developer:** Community member "Jagula"
- **Status:** Alpha / proof of concept
- **Interface:** Official Unraid GraphQL API
- **Install:** `Install-Module PSUnraid`
- **Capabilities:** Server/array/disk status, Docker/VM start/stop/restart, notifications
- **Requires:** Unraid 7.2.2+ for full feature support
- **Key insight:** Remote-only (no SSH needed), converts JSON to PowerShell objects

#### 3. unraid-management-agent (Go Plugin)
- **Interface:** **NOT** the official GraphQL API -- independent REST API + WebSocket
- **Port:** Default 8043
- **Architecture:** Standalone Go binary, collects data via native libraries
- **Endpoints:** 50+ REST endpoints, `/metrics` for Prometheus, WebSocket at `/api/v1/ws`
- **Integrations:** Prometheus (41 metrics), MQTT, Home Assistant (auto-discovery), MCP (54 tools)
- **Key insight:** Provides data the official API lacks (SMART data, container logs, process monitoring, GPU stats, UPS data)

#### 4. unraid-ssh-mcp
- **Interface:** SSH (explicitly chose NOT to use GraphQL API)
- **Reason:** API lacked container logs, SMART data, real-time CPU load, process monitoring
- **Advantage:** Works on any Unraid version, no rate limits

#### Other Projects
- **U-Manager:** Android app for remote Unraid management
- **Unraid Deck:** Native iOS client (SwiftUI)
- **hass-unraid:** Home Assistant integration with SMART attribute notifications

**Sources:**
- [PSUnraid Reddit Thread](https://www.reddit.com/r/unRAID/comments/1ph08wi/psunraid_powershell_m) [Tier: Community]
- [unraid-management-agent GitHub](https://github.com/ruaan-deysel/unraid-management-agent) [Tier: Official]
- [Unraid MCP Reddit Thread](https://www.reddit.com/r/unRAID/comments/1pl4s4j/unraid_mcp_server_que) [Tier: Community]

---

## 9. Known Issues and Limitations

### GraphQL Schema Issues (Discovered in unraid-mcp Development)

Based on the existing unraid-mcp codebase, the following issues have been encountered:

1. **Int Overflow on Large Values:** Memory size fields (total, used, free) and some disk operation counters can overflow GraphQL's standard 32-bit `Int` type. The API uses a custom `Long` scalar but some fields still return problematic values.

2. **NaN Values:** Certain fields in the `vars` query (e.g., `sysArraySlots`, `sysCacheSlots`, `cacheNumDevices`, `cacheSbNumDisks`) can return NaN, causing type errors. The existing codebase works around this by querying a curated subset of fields.

3. **Non-nullable Fields Returning Null:** The `info.devices` section has non-nullable fields that may be null in practice. The codebase avoids querying this section entirely.

4. **Memory Layout Size Missing:** Individual memory stick `size` values are not returned by the API, preventing total memory calculation from layout data.

### API Coverage Gaps

According to the unraid-ssh-mcp developer, the GraphQL API currently lacks:
- Docker container logs
- Detailed SMART data for drives
- Real-time CPU load averages
- Process monitoring capabilities
- Some system-level metrics available via `/proc` and `/sys`

### General Limitations

- **Rate Limiting:** The API implements rate limiting (specific limits not documented publicly)
- **Version Dependency:** Full API requires Unraid 7.2+; pre-7.2 versions need the Connect plugin
- **Self-Signed Certificates:** Client must handle SSL verification for local IP access
- **Schema Volatility:** The API schema is still evolving; field names and types may change between versions

---

## 10. API Roadmap and Future Features

### Completed (as of 7.2)
- API native to Unraid OS
- Separated from Connect Plugin
- Open-sourced
- OIDC/SSO support
- Permissions system rewrite (v4.0.0)

### Q1 2025
- New Connect Settings Interface

### Q2 2025
- New modernized Settings Pages
- Storage Pool Creation Interface (simplified)
- Storage Pool Status Interface (real-time)
- Developer Tools for Plugins
- Custom Theme Creator (start)

### Q3 2025
- Custom Theme Creator (completion)
- New Docker Status Interface
- Docker Container Setup Interface (streamlined)
- New Plugins Interface (redesigned)

### TBD (Planned but Unscheduled)
- **Native Docker Compose support** -- Highly anticipated
- Plugin Development SDK and tooling
- Advanced Plugin Management interface
- Storage Share Creation & Settings interfaces
- Storage Share Management Dashboard

### In Development
- User Interface Component Library (security components)

**Sources:**
- [Roadmap & Features | Unraid Docs](https://docs.unraid.net/API/upcoming-features/) [Tier: Primary]

---

## 11. Recommendations for unraid-mcp

Based on this research, the following improvements are recommended for the unraid-mcp project:

### High Priority

1. **ZFS/Pool Management Tools**
   - Add `get_pool_status` for ZFS/BTRFS storage pools
   - Current `get_array_status` insufficient for multi-pool setups introduced in Unraid 7.0

2. **Scope-Based Tool Filtering**
   - Before registering tools with MCP, verify the API key has appropriate permissions
   - Prevent exposing tools the key cannot use (avoid hallucinated capabilities)
   - Query current key permissions at startup

3. **Improved Error Handling**
   - Implement exponential backoff for rate limit errors (HTTP 429)
   - Better handling of `Long` scalar type values
   - Graceful degradation for unavailable schema fields

4. **API Key Authorization Flow**
   - Consider implementing the OAuth-like flow (`/ApiKeyAuthorize`) for user-friendly key generation
   - Enables scope-based consent before key creation

### Medium Priority

5. **Real-Time Notification Streaming**
   - Add WebSocket subscription for notifications
   - Allows proactive alerting (e.g., "Disk 5 is overheating") without user request

6. **File Manager Integration**
   - Add `list_files`, `read_file` tools using the native File Manager API (merged in 7.0)
   - Enables LLM to organize media or clean up `appdata`

7. **Pagination for Large Queries**
   - Implement `limit` and `offset` for log listings and file browsing
   - Prevent timeouts from massive result sets

8. **Flash Backup Trigger**
   - Add tool to trigger flash backup via API mutation
   - Monitor backup status

### Low Priority

9. **VM Snapshot Management**
   - Add `create_vm_snapshot`, `revert_to_snapshot`, `clone_vm`
   - Leverages QEMU snapshot support from Unraid 7.0

10. **Tailscale/VPN Status**
    - Query network schemas for Tailnet IPs and VPN connection status
    - Useful for remote management diagnostics

11. **Query Complexity Optimization**
    - Separate list queries (lightweight) from detail queries (heavy)
    - `list_docker_containers` should fetch only id/names/state
    - Detail queries should be on-demand

### Implementation Notes

- **GraphQL Sandbox Discovery:** Use the built-in sandbox at `http://SERVER/graphql` to discover exact mutation names and field types for any new tools
- **Version Compatibility:** Consider checking the Unraid API version at startup and adjusting available tools accordingly
- **SSL Configuration:** The `UNRAID_VERIFY_SSL` environment variable is already implemented -- ensure documentation guides users toward `myunraid.net` certificates for proper SSL
- **PrefixedID Handling:** Container and VM IDs use the `PrefixedID` custom scalar -- ensure all ID-based operations handle this string type correctly

---

## 12. Source Bibliography

### Primary Sources (Official Documentation)
- [Welcome to Unraid API | Unraid Docs](https://docs.unraid.net/API/)
- [Using the Unraid API](https://docs.unraid.net/API/how-to-use-the-api/)
- [API key authorization flow | Unraid Docs](https://docs.unraid.net/API/api-key-app-developer-authorization-flow/)
- [Programmatic API key management | Unraid Docs](https://docs.unraid.net/API/programmatic-api-key-management/)
- [Roadmap & Features | Unraid Docs](https://docs.unraid.net/API/upcoming-features/)
- [Unraid Connect overview & setup | Unraid Docs](https://docs.unraid.net/connect/about/)
- [Remote access | Unraid Docs](https://docs.unraid.net/connect/remote-access/)
- [Automated flash backup | Unraid Docs](https://docs.unraid.net/connect/flash-backup/)
- [Version 7.0.0 Release Notes](https://docs.unraid.net/unraid-os/release-notes/7.0.0/)
- [Version 7.0.1 Release Notes](https://docs.unraid.net/unraid-os/release-notes/7.0.1/)
- [Version 7.1.0 Release Notes](https://docs.unraid.net/unraid-os/release-notes/7.1.0/)

### Official / GitHub Sources
- [GitHub - unraid/api: Unraid API / Connect / UI Monorepo](https://github.com/unraid/api)
- [GitHub - jmagar/unraid-mcp](https://github.com/jmagar/unraid-mcp)
- [api/docs/developer/development.md](https://github.com/unraid/api/blob/main/api/docs/developer/development.md)
- [Unraid OS 7.2.0 Blog Post](https://unraid.net/blog/unraid-7-2-0)

### Community Sources
- [PSUnraid PowerShell Module (Reddit)](https://www.reddit.com/r/unRAID/comments/1ph08wi/psunraid_powershell_m)
- [Unraid MCP Server (Reddit)](https://www.reddit.com/r/unRAID/comments/1pl4s4j/unraid_mcp_server_que)
- [unraid-management-agent (GitHub)](https://github.com/ruaan-deysel/unraid-management-agent)
- [Unraid API Discussion (Reddit)](https://www.reddit.com/r/unRAID/comments/1h7xkjr/unraid_api/)
- [API Key Location Question (Reddit)](https://www.reddit.com/r/unRAID/comments/1nk2jjk/i_couldnt_find_the_ap)

### Reference Sources
- [GraphQL Specification](https://spec.graphql.org/)
- [Learn GraphQL](https://graphql.org/learn/)
- [GraphQL Subscriptions](https://graphql.org/learn/subscriptions/)
- [Apollo GraphQL Sandbox](https://www.apollographql.com/docs/graphos/platform/sandbox)
- [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction)

---

## Cross-Source Analysis

### Where Sources Agree
- The API is GraphQL-based with queries, mutations, and subscriptions
- Unraid 7.2 is the version where API became native
- API Keys are the primary authentication method for programmatic access
- The endpoint is at `/graphql` on the server
- The API supports Docker/VM lifecycle management
- The monorepo is TypeScript/Node.js based

### Where Sources Disagree or Have Gaps
- **Exact mutation names** are not documented publicly -- must use GraphQL Sandbox introspection
- **Rate limit specifics** (thresholds, headers) are not publicly documented
- **Container logs** -- the unraid-ssh-mcp developer claims they're unavailable via API, but this may have changed in newer versions
- **Schema type issues** (Int overflow, NaN) are documented only in the unraid-mcp codebase, not in official docs

### Notable Insights
1. The unraid-management-agent project provides capabilities the official API lacks, suggesting areas for API expansion
2. PSUnraid confirms the API schema includes mutations for Docker/VM lifecycle with boolean return types
3. The OAuth-like authorization flow is a sophisticated feature not commonly found in self-hosted server APIs
4. The `Long` scalar type and `PrefixedID` type are custom additions critical for proper client implementation