AI-Assisted Fleet Operations (MCP Server)
The Admiral MCP server is open source at github.com/AdmrlOS/admiral-mcp. It runs on your machine, talks to Admiral with a personal API token, and works with any MCP client.
Admiral provides a Model Context Protocol (MCP) server that connects AI assistants and agents (such as Claude Code, Cursor, and your own tooling) to your fleet. Ask in plain language: "Which devices are offline?", "What is the IP of the printer?", "Grab the logs from the crashing kiosk and tell me why."
With the MCP server, an assistant can query device health, read logs, troubleshoot a device end to end, search this documentation, and run authorized remediation tasks safely. It uses the same tools as AdmiralAI, the assistant built into the dashboard, apart from the two streaming watch_ tools, which AdmiralAI does not offer.
Model Context Protocol (MCP) Integration Topology
Authenticated via Fine-Grained IAM Tokens with Audit-Logged Execution
Capabilities Provided by the MCP Server
- Fleet Health Inspection: Query real-time device health, CPU/memory gauges, thermals, battery states, and network latency across all enrolled machines.
- Log Retrieval & Diagnostic Analysis: Retrieve kernel, supervisor, and container logs, and get a one-call troubleshooting report with ranked findings, evidence, and next steps.
- Desired State as Documents: Read and patch device documents, preview what a device would receive, and adopt or discard settings changed on site.
- Documentation Search: Search and read docs.admrl.co, so the assistant can answer how-to questions and link the page it used.
- Controlled Canary Rollouts: Create configuration rollouts with a canary, in-flight limit, and failure budget; watch them converge; pause, resume, cancel, or roll back.
- Device Control & Remediation: Issue authorized reboots and workload restarts on devices experiencing anomalies.
- Security & IAM Scoping: All MCP actions authenticate against Admiral's fine-grained IAM policy engine, ensuring AI agents operate strictly within explicitly granted permission boundaries.
Tools accept a device by name, tag, notes, IP, or UUID and resolve it first; an ambiguous match returns candidates and changes nothing. Tools that change something are not marked read-only, so the client asks before running them, and tools that can disrupt a device, a configuration, or a rollout are also marked destructive; only call them on an explicit request.
Install and Connect
1. Create a token
In the dashboard, open Account > API tokens and create a personal token. The secret is shown once. The MCP server authenticates with personal tokens. A personal token cannot be narrowed to a specific role; it inherits all capabilities of the user account that created it. To limit what an assistant can do, create a dedicated user account assigned a narrow Role (such as Viewer or Technician), or configure automation via a scoped service account.
2. Run the server
You need Python 3.11 or later and uv.
git clone https://github.com/AdmrlOS/admiral-mcp.git
cd admiral-mcp
uv sync
The server speaks MCP over stdio and reads its credentials from the environment:
| Variable | Purpose |
|---|---|
ADMRL_API_TOKEN_ID | The token ID (starts with admk_), sent as X-API-Token-ID. |
ADMRL_API_SECRET_KEY | The token secret (starts with adms_), sent as X-API-Secret-Key. |
ADMRL_ORG_ID | The organisation to act in, sent as X-Organization-ID. Optional if the token can see only one organisation; otherwise use list_organisations to find it. |
To check it starts:
export ADMRL_API_TOKEN_ID=...
export ADMRL_API_SECRET_KEY=...
export ADMRL_ORG_ID=...
uv run admrl-mcp
3. Add it to your MCP client
Register uv run admrl-mcp as a stdio server, with the three variables passed explicitly (many clients do not forward your shell environment to MCP subprocesses). For a client that uses a JSON configuration:
{
"mcpServers": {
"admiral": {
"command": "uv",
"args": ["--directory", "/path/to/admiral-mcp", "run", "admrl-mcp"],
"env": {
"ADMRL_API_TOKEN_ID": "admk_...",
"ADMRL_API_SECRET_KEY": "adms_...",
"ADMRL_ORG_ID": "<organisation id>"
}
}
}
}
Restart the client so it picks up the new server. Keep the secret out of files you commit.
get_device_logs queries stored history, which also works for offline devices.
Tool Reference
Find and inspect
| Tool | What it returns |
|---|---|
list_organisations, list_fleets, list_devices, search | Organisations, fleets (search, tag filter), devices (status, fleet, free-text filter), and organisation-wide search. |
find_device | Resolve a device from a natural query; returns one match or ranked candidates. |
get_device, get_device_specs, get_device_network | Device detail, hardware and OS specification, IP addresses and interfaces. |
get_device_workload, get_device_system_services | Workload state and running configuration; platform services and whether any are crash-looping. |
get_device_stats, get_device_metrics | Latest CPU, memory, disk, and health; historical metric series. |
get_device_logs, get_device_events | Historical logs (works for offline devices); lifecycle events. |
get_device_policy | The device's effective policy: what is requested (organisation, fleet, device), what the device reports running, and anything it had to clamp. |
get_device_screenshot | Live capture of the device's display (online devices). |
Troubleshooting
| Tool | What it returns |
|---|---|
troubleshoot_device | "What is wrong with this device?" in one call. Combines the device state, the diagnosis, a fresh probe, recent error logs, events, workload and storage state, clock sync, connectivity, and drift between assigned and applied configuration. Returns ranked findings, each with evidence, the likely cause, what you can do now, a documentation link, and whether Admiral support is needed. An optional symptom ("screen is black", "keeps rebooting") promotes related findings. Works for offline devices from stored data. |
check_device_connectivity | Link, DNS, TCP, clock, and transport checks as a pass, warn, or error table, with the usual causes (captive portal, DNS, firewall, TLS inspection or proxy, clock skew, weak link). Runs a live network probe when the device is online. |
explain_workload_failure | Why a workload is failing: crash loops and exit codes, out-of-memory kills, image pull errors, signature and USB policy denials, rollbacks, and stuck updates, with scrubbed log excerpts. Log excerpts need the Telemetry add-on. |
fleet_health_report | Devices by status for a fleet or the whole organisation, offline devices by how long they have been gone, and devices grouped by their top problem. Bounded: it samples devices and says how many it did not diagnose. |
Documentation
| Tool | What it does |
|---|---|
search_docs | Search docs.admrl.co and return matching pages with a snippet and URL. Needs no Admiral credentials and sends none. |
read_docs_page | Read one documentation page by URL or path, section by section. |
State and diagnostics
| Tool | What it returns |
|---|---|
diagnose_device | The diagnosis: verdict, severity-ordered issues with evidence, last reboot. Stored data only; works offline. |
get_device_state | Conditions, observed generation, workload, boot, transport, time, storage, boot reasons, live operations, local override. live=true asks the device now. |
watch_device_state | Follows the device's state stream for up to 10 minutes and returns condition transitions and every progress operation seen. |
probe_device | Runs the live probe on the device (optionally only some sections). Support-scope values come back [redacted]. |
Documents
| Tool | What it does |
|---|---|
get_device_document | The device's document as JSON or YAML, with its resource version. |
patch_device_document | Apply a JSON merge patch (for example a fleet move or a workload override), optionally with if_match. Destructive. |
render_device_document | Dry-run render: what the device would receive and the diff against what it applied. |
adopt_local_override, discard_local_override | Adopt on-site settings into the document, or tell the device to drop them. Discard can take connectivity away from a device; destructive. |
Fleets and configurations
| Tool | What it does |
|---|---|
duplicate_fleet, duplicate_configuration | Copy a fleet (settings and policies, never devices or billed features) or a configuration (secret files are not copied) under a new name, and report anything that was skipped. Creates a resource; explicit request only. |
Rollouts
| Tool | What it does |
|---|---|
create_rollout | Create a configuration rollout for a fleet, configuration, and version with an optional strategy (canary, max in flight, max unavailable, failure threshold, progress deadline). Destructive. |
get_rollout, list_rollout_devices | Status, paused reason, strategy, counts; per-device phase, progress, and stuck time. |
rollout_control | pause, resume, cancel, or rollback. Destructive. |
watch_rollout | Follow a rollout until it finishes or a timeout, returning status and per-device phase transitions. |
Memory tests
| Tool | What it does |
|---|---|
start_memory_test | Start a live test (workload keeps running; optional quick preset) or a full_online test (workload stopped; needs confirm=true). A test boot is not available here. Destructive. |
cancel_memory_test | Cancel the running test. |
get_memory_test | Current or last run, memory health, and recent results. |
list_memory_test_results | Stored results, newest first. |
Actions
| Tool | What it does |
|---|---|
reboot_device | Reboot a device. Destructive. |
change_workload_status | Start, stop, restart, or recreate the workload. Destructive. |
Support tickets
| Tool | What it does |
|---|---|
create_support_ticket | Raise a support ticket, optionally about one device, fleet, or configuration, and optionally request a diagnostics bundle for a device. Urgent tickets are refused; raise those from the dashboard. Creates a resource; explicit request only. |
list_support_tickets | The organisation's support tickets. |
Census
| Tool | What it returns |
|---|---|
list_fleet_protocols | Read-only count of the organisation's devices by wire protocol (0 for legacy container push, 1 for desired-state documents, no_state for devices that have never reported state) and by agent version, with the per-device list. Optional fleet filter. |
Safety
- Every call runs with the permissions of your token and is an ordinary API request, so it appears in the audit log on accounts that have one.
- Tools that change something are not marked read-only, so a well-behaved client asks you before running them; tools that can disrupt a device, a configuration, or a rollout are also marked destructive. Because personal tokens inherit all permissions of the creating user, run the MCP server with a dedicated user assigned a narrow role, and review each request before you approve it.
- Text from devices (names, hostnames, log lines) reaches the assistant as tool output. A hostile string could try to steer a model, and no assistant is immune to this. Keep destructive approvals manual and identities narrowly scoped.
- The server can be extended with additional tool packages. Each tool must declare whether it is read-only, and a package that does not is rejected.
Using AdmiralAI Instead
If you only want to ask questions from the dashboard, use AdmiralAI. It runs these tools for you with your signed-in permissions, with no token to create, and shows approval cards for anything that changes a device.