Work Intent: Add native MCP support to Unraid API

[ruaan-deysel]

Overview

Add native Model Context Protocol (MCP) server support to the Unraid API, enabling AI assistants
(Claude, GPT, Gemini, GitHub Copilot, etc.) to securely interact with an Unraid server through
a standardised, LLM-native interface.

MCP is rapidly becoming the de-facto standard for AI agent integration. Without native MCP support,
Unraid users who want AI-assisted management must rely on third-party wrappers or unofficial plugins.

This proposal exposes the existing GraphQL API surface as MCP tools, resources, and prompts via a
dedicated /mcp HTTP+SSE endpoint, without altering or replacing any existing API behaviour.

Technical Approach

The MCP server will be implemented as an additional transport layer over the existing Unraid GraphQL
API, following the MCP 2025-06-18 specification.

Endpoint: POST /api/mcp (JSON-RPC 2.0 over HTTP with Server-Sent Events for streaming)

Three capability types will be exposed:

1. Tools - Callable functions that invoke GraphQL mutations or queries with side effects.
   Examples:

   • get_system_info → wraps query { info { ... } }
   • get_array_status → wraps query { array { ... } }
   • start_docker_container(id) → wraps mutation { startContainer(...) }
   • stop_vm(id) → wraps mutation { stopVM(...) }
   • get_disk_info / get_network_interfaces / get_shares
   • get_notifications / acknowledge_notification(id)

2. Resources - Read-only data objects accessible via URI, ideal for LLM context injection:

   • unraid://system/info - live system snapshot
   • unraid://array/status - array state and parity info
   • unraid://docker/containers - container list and states
   • unraid://vms - VM inventory and states
   • unraid://notifications - active alerts

3. Prompts - Reusable parameterised templates to guide AI interactions:

   • unraid-health-check - structured prompt for full system health review
   • unraid-troubleshoot(component) - targeted troubleshooting workflow
   • unraid-maintenance-summary - produces a human-readable maintenance report

Authentication: MCP requests will be authenticated using the existing Unraid API key mechanism
(passed via Authorization: Bearer <api-key> header), with read-only and read-write scopes
enforced per-tool. Destructive operations (array stop, VM force-stop) will require an explicit
write-scoped API key.

Implementation notes:

• MCP server layer sits alongside the existing GraphQL endpoint - no changes to GraphQL schema
• JSON Schema used for all tool input validation (MCP spec requirement)
• Stateless request handling; no session persistence required
• Compatible with MCP clients: Claude Desktop, VS Code + GitHub Copilot, Cursor, Claude Code

Scope

• API
• Plugin
• Web UI
• Build/Deploy Process
• Documentation

Timeline & Impact

• Estimated time needed: 3–4 weeks (1 week protocol handler + 2 weeks tool/resource/prompt
  coverage + 1 week testing and documentation)
• Potential impacts:
  • No breaking changes - additive endpoint only; existing GraphQL API and auth unchanged
    • Requires Unraid 7.2+ (API is native from that version)
    • MCP endpoint will be gated behind the existing API enabled/disabled toggle in
      Settings → Management Access → API
    • Community MCP clients will need to be pointed to http://<unraid-ip>/api/mcp

Pre-submission Checklist

• I have searched for similar work/issues
• I understand this needs approval before starting
• I am willing to make adjustments based on feedback