Usage¶

Once the server is in your client (see Configuration), you talk to your devices through the client. This page is what the client sees: 7 resources it can read and 12 tools it can call, and which of them change something.

Example prompts¶

"Which devices have not informed in the last 24 hours?" (the client calls search_devices with a _lastInform filter)
"What firmware do the devices tagged pilot run?" (search_devices by tag, then get_parameter for InternetGatewayDevice.DeviceInfo.SoftwareVersion on each)
"Reboot 202BC1-BM632w-000002 and tell me when it is back" (reboot_device, then refresh_parameter for the uptime)

MCP Inspector, Tools tab: the genieacs-mcp tool list (ten of the twelve fit the view), search_devices selected with its description and its query and limit fields

Resources (read-only)¶

URI	Returns
`genieacs://devices/list`	The ids of every device the ACS knows, up to `DEVICE_LIMIT` (default 500). Read this first to get valid ids.
`genieacs://device/{id}`	One device's full document: every parameter the ACS has collected, tags, last inform time, task history.
`genieacs://tasks/{id}`	The tasks still waiting for device `{id}`. GenieACS deletes a task once the device has run it, so a finished task is gone; a faulted one stays, with its fault under `faults/{id}`.
`genieacs://faults/{id}`	The faults recorded for device `{id}`.
`genieacs://file/{name}`	The metadata of a file stored on the ACS (a firmware image, a config file).
`genieacs://presets/list`	Every preset on the ACS.
`genieacs://provisions/list`	Every provision script on the ACS.

MCP Inspector, Resources tab: the three list resources and four resource templates of genieacs-mcp, with genieacs://devices/list read and six simulated device ids in the preview

Tools¶

Two tools only read. The other ten queue a task on a device (the ACS sends a connection request at once, so a reachable device runs it within seconds), wake a device, or change the ACS. Each tool's annotations say which. The two readers carry readOnlyHint. The rest say whether they are destructive and whether running them twice is the same as once, so your client can ask before the ones that act. GENIEACS_READ_ONLY=true serves only the two readers, and GENIEACS_TOOLS serves only the tools you name (see Configuration).

Tool	Arguments	What it does	Reads or acts
`search_devices`	`query` (JSON string, MongoDB syntax), `limit` (1 to 200, default 50), `skip`, `projection` (default a summary; `all` for full documents), `sort` (JSON, e.g. `{"_lastInform":-1}`)	Finds devices by tag, manufacturer, model, firmware, last inform or any parameter. Query operators such as `$eq`, `$ne`, `$gt`, `$lt`, `$in`, `$nin`, `$exists`, `$regex`, `$and` and `$or` work; `$where`, `$function`, `$accumulator` and `$expr` are refused because they run code on the ACS database, and a `$regex` pattern may be at most 256 characters. Returns `count`, `more` (another page exists) and the devices.	reads
`get_parameter`	`device_id`, `parameter_path` (one path or a comma-separated list)	Returns the last values the ACS has for those parameters, without contacting the device, as `parameters` (path to `value`, `type`, `timestamp`) plus the paths it has no value for in `missing`. Stale if the device has not informed recently.	reads
`refresh_parameter`	`device_id`, `parameter`	Asks the device to report one parameter's current value; read it afterwards from `genieacs://device/{id}`.	acts
`set_parameter`	`device_id`, `parameter_values` (JSON array of `[path, value]` or `[path, value, xsdType]` tuples; example below the table)	Writes parameter values on the device; the type is inferred when omitted.	acts
`reboot_device`	`device_id`	Reboots the device. No confirmation that it came back; check uptime afterwards.	acts
`download_firmware`	`device_id`, `file_id`, `filename` (optional)	Tells the device to download and apply a file stored on the ACS.	acts
`connection_request`	`device_id`	Wakes the device so it contacts the ACS now. Fails with 504 when the device is unreachable (NAT, offline).	acts
`tag_device`	`device_id`, `tag`, `action` (`add` or `remove`)	Adds or removes a tag; presets match on tags.	acts
`manage_preset`	`action` (`put` or `delete`), `name`, `body` (JSON, for `put`)	Creates, replaces or deletes a preset on the ACS.	acts
`manage_provision`	`action` (`put` or `delete`), `name`, `script` (for `put`)	Creates, replaces or deletes a provision script on the ACS.	acts
`delete_task`	`task_id`	Removes a queued task.	acts
`retry_task`	`task_id`	Re-queues a failed task.	acts

A parameter_values example for set_parameter, renaming the WiFi network:

[
  [
    "InternetGatewayDevice.LANDevice.1.WLANConfiguration.1.SSID",
    "Lab-2",
    "xsd:string"
  ]
]

The two readers (search_devices, get_parameter) and the four task tools below answer with structured content as well as text, and declare their output schema; the other six tools answer with text. The tools that queue a task (refresh_parameter, set_parameter, reboot_device, download_firmware) return status: done when the device ran the task during the call (the NBI answered 200), queued when it was not reachable in time and the task waits for its next inform (202). A queued task is listed under genieacs://tasks/{id} until it runs.

MCP Inspector, Tools tab: set_parameter run on a simulated device to change its WiFi SSID, the result showing the setParameterValues task document the ACS returned

On the wire¶

The client speaks MCP JSON-RPC to the server. A 2026-07-28 client may start with server/discover and send its protocol version on every request; an older one starts with initialize. After that both use resources/list, resources/read, tools/list and tools/call. The list results carry a five-minute cache hint, so a client need not ask again on every turn. Over HTTP everything goes to the single /mcp endpoint; over stdio, one JSON-RPC message per line. A worked exchange is on Getting started.