Skip to content
Port OS

endpoint_show

← MCP reference
View in MCP reference →
TOOL endpoint_show

Show Port OS devices with their supported controls.

To show a device, always call this tool: the widget it opens is the device's UI, so never render a second card, map or controls for it; answer in a sentence or two.

Uses the same selection, expansion and pagination arguments as endpoint_query. A single matching device opens its full view with now playing, transport, volume and other controls; several matches open only a list of names to choose from, so pass one full endpoint ID (or a query matching one device) to control a device. Showing a device does not start live video or send a control command.

Pass primary to choose which card leads, one of the device's card ids (every result lists them as cardIds; an unknown id is rejected with the available ones). The device's usual card and every other card stay behind the details toggle. Examples: "what's the battery on the vacuum" -> primary battery; "turn the thermostat fan on" -> primary fan; "how open are the blinds" -> primary closure; "show me the camera on the roborock" -> primary camera. "where is my phone" or "show its location" -> primary location; "show the roborock's map" or "pick a room to clean" -> primary house-map. Every result already includes the cached readings of the cards it lists (cardIds), so you can answer without a second call; pass expand to choose different capabilities. primary refreshes that card's readings from the device, so the answer is current. Always state the value in words: a FRESH reading is current; a STALE reading is the last known value, so say it is last known and give its age.

Required scope

endpoint:read

Input

Fields

enablementstring

Filter by ENABLED (default), DISABLED, or * for both. This filter is preserved by pagination.

Default: ENABLED

Allowed values: ENABLED, DISABLED, *.

endpointIdstring

Return one endpoint by its full Port OS identifier. Cannot be combined with other filters or pagination. Results advertise its declared command and outbound message IDs.

expandarray<string>

Select observations to add to each device result, for example ["power", "connectivity"] or ["battery"]. Use capability names or full namespaces declared by the device. This reads attributes; it does not send commands or broaden the device search. Short names use port1/systems/zero/capability-interfaces. endpoint_show already includes cached readings for the cards it lists; expand replaces that selection.

forceDeviceAttributeQueryboolean

Read selected attributes from devices instead of cache. Requires nonempty expand. Failed reads remain unavailable.

maxResultsinteger

Maximum number of results (default 10, maximum 100).

minimum: 1

nextTokenstring

Opaque cursor returned by a previous endpoint_query call.

primarystring

The card to lead with, one of the device's card ids (shown as cardIds in the result), for example battery, fan, closure, thermostat, camera or remote; house-map for a vacuum's map or room picking (never draw your own map). Needs endpointId. Every other card stays behind the details toggle.

queryobject

Optional field-first filter. Omit it to load full context; filter only when the account is large. Each key is a field or a combinator, and all keys of one object must match: {"name": {"like": "living"}, "type": {"in": ["LIGHT", "SWITCH"]}}. Combinators: {"and": [query, ...]}, {"or": [query, ...]}, {"not": query}. Text operators: eq (exact), in (any of a list), like (case-insensitive substring), lt and gt (lexical order). List operators: has (contains the exact value), like (some value contains the substring, case-insensitive). Fields: the fields your connected devices declare, listed in the tool description returned by tools/list.

Result

Fields

(payload)object