Skip to main content
Glama

Manage App (add-on)

ha_manage_app
Destructive

Install, update, start, stop, or configure Home Assistant apps (add-ons), and proxy documented app APIs for read/write access. Use it to manage app lifecycle, settings, ports, and repositories.

Instructions

Manage Home Assistant apps (add-ons) or proxy an app API.

For app inventory, status, and Supervisor metadata, call ha_get_app first; use proxy mode here for documented app-specific read APIs, and do not infer private app API schemas.

Use exactly one mode: lifecycle/store action, configuration fields, path proxy, or path with array_patch.

Requires Home Assistant OS or Supervised. When ha-mcp itself runs as an app it cannot update its own running slug; update ha-mcp from the Home Assistant Apps UI. options merges top-level keys and one nested mapping level; supply complete values for deeper nested mappings because they are replaced. Prefer Ingress: direct-port access requires a shared container network and may require weakening the target app authentication. If a Supervisor lifecycle, configuration, or repository write has an unknown outcome, verify durable state with ha_get_app before retrying. That cannot prove whether restart or rebuild ran; inspect Supervisor jobs and logs and do not automatically replay them. For a proxy or array-patch write, query the target app's own read API before retrying.

If a Claude Desktop user gets a 4-minute timeout with no result on this call, read the target back before repeating it, and tell them to wait a few seconds before clicking the manual-approve button, as clicking it too quickly is known to cause hangs in Claude Desktop. This workaround is specific to Claude Desktop.

manage app apps addon add-on configure settings options port network boot watchdog auto_update supervisor ingress proxy websocket api rest esphome nodered node-red frigate mosquitto mqtt zigbee2mqtt zigbee z-wave zwave appdaemon hacs studio code server file editor terminal ssh samba grafana influxdb deconz motioneye compile validate upload deploy firmware ota flash yaml device logs flows events stats

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "ha_manage_app"
  }
}

Input Schema

NameRequiredDescriptionDefault
bodyNoProxy mode only. Request body for POST/PUT/PATCH — or, with websocket=True, the initial WebSocket message. Pass a JSON object or JSON string.
bootNoConfig mode: Boot strategy — 'auto' (start with HA) or 'manual'.
pathNoProxy mode: API path relative to the app (add-on) root (e.g., '/flows', '/api/events', '/api/stats'). Required for proxy mode. ESPHome 2026.10+: POST JSON-RPC to '/api/mcp' (initialize, notifications/initialized, tools/list, then tools/call); check response.error first, then response.result.isError.
portNoProxy mode only. Connect to this port instead of the Ingress port. Use ha_get_app(slug='...') to find available ports. Some apps, including Node-RED and ESPHome, reject direct access unless their leave_front_door_open option is enabled and the app is restarted.
slugNoApp (add-on) slug (e.g., '<prefix>_nodered', '<prefix>_frigate'). Slug prefixes vary by app repository — call ha_get_app() to discover the actual installed slug. Required except for action='add_repository' / 'remove_repository' (which take 'repository' instead) and action='check_updates' (which takes neither).
debugNoProxy mode only. Include diagnostic info (request URL, headers sent, response headers).
limitNoProxy mode only. HTTP: return at most this many items from a JSON array response.
actionNoLifecycle mode: run a Supervisor app (add-on) action. One of 'install', 'uninstall', 'start', 'stop', 'restart', 'rebuild', 'update'. 'install'/'update' require the app's repository to be registered (it appears in ha_get_app(source='available')); 'rebuild' is for a local app whose source changed but whose version did not. Store-repository mode: 'add_repository' / 'remove_repository' register or unregister a custom app store repository — these use the 'repository' param instead of 'slug'. Store-wide mode: 'check_updates' reloads the store so Supervisor re-scans its repositories (e.g. after editing a local app's config.yaml) — it takes neither 'slug' nor 'repository', refreshes available metadata only, and installs nothing; follow with action='update' for a newer version, or action='rebuild' for a local app whose source changed without a version change. Returns 'changed' and 'updates_available', null when the store could not be read (see 'warnings').
methodNoProxy mode only. HTTP method: GET, POST, PUT, DELETE, PATCH.GET
offsetNoProxy mode only. HTTP: skip this many items in a JSON array response.
networkNoConfig mode: Complete desired host-port override map (e.g., {'5800/tcp': 8081}). A non-empty map replaces current overrides, so omitted entries are cleared. Omit 'network' to leave mappings unchanged. An empty map is ignored and does not by itself select config mode.
optionsNoConfig mode: App (add-on) configuration values (the 'Configuration' tab in the UI).
watchdogNoConfig mode: Enable or disable Supervisor watchdog (auto-restart on crash).
summarizeNoProxy mode only. WebSocket: when True, collapse runs of non-signal messages (typically YAML config dumps) into short elision markers. Set to False to return the raw stream.
websocketNoProxy mode only. Use WebSocket instead of HTTP for an app (add-on) WebSocket API. Sends 'body' as the initial message and collects responses; command names and body schemas are app/version-specific.
repositoryNoStore-repository mode only (action='add_repository' or 'remove_repository'). For add_repository: the repository URL (e.g., 'https://github.com/balloob/home-assistant-addons'). For remove_repository: the repository slug (e.g., '0f1cc410', as shown in ha_get_app(source='available')). Required for those actions; rejected otherwise.
array_patchNoArray-patch mode: atomically GET a JSON array endpoint, apply ordered ops, then POST the mutated array back. Requires 'path'; mutually exclusive with body / websocket / offset / limit and config params. Use ha_get_skill_guide for operation shapes.
auto_updateNoConfig mode: Enable or disable automatic updates for this app (add-on).
message_limitNoProxy mode only. WebSocket: cap on messages collected from the wire, bounded by an internal safety ceiling. None = collect up to the ceiling.
message_offsetNoProxy mode only. WebSocket: drop this many messages from the start of the collected list before returning.
wait_for_closeNoProxy mode only. WebSocket: True waits for the server to close a run-to-completion stream. False returns after the first response batch; use for one-shot command/response or bounded capture on a channel that stays open.
request_headersNoProxy/array-patch mode: extra HTTP headers for the app (add-on) API. Useful for app-specific requirements such as Node-RED's `Node-RED-Deployment-Type: full`. Ingress routing headers override caller values on Ingress routes; direct-port calls have no internal routing headers. `Content-Type` is derived from the body when supplied. Not valid in config or websocket mode.
python_transformNoProxy mode only. Sandboxed Python expression that post-processes the response. Variable `response` is exposed — a list[dict | str] for WebSocket (parsed JSON or raw text), or dict/list/str for HTTP (parsed body). Supports in-place mutation (response.append(...)) or reassignment (response = [...]). Example: response = [m for m in response if 'ERROR' in str(m)].

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv9.2.0

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The annotations already flag this as destructive, non-readonly, non-idempotent, and open-world, but the description adds substantial operational context beyond them: HA OS/Supervised is required, ha-mcp cannot update its own running slug, unknown lifecycle/config/repository outcomes must be verified with `ha_get_app`, and restart/rebuild outcomes cannot be proven by that verification. It also discloses merge/replace semantics for `options` and `network`, and retry guidance for proxy/array-patch writes.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with purpose and mode-routing guidance, then proceeds to operational caveats in a mostly logical order. It is long, but the complexity of a 23-parameter multi-mode tool justifies much of the length; the trailing keyword list is the main conciseness weakness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity, 23 parameters, and high schema coverage, the description is unusually complete: it covers mode selection, prerequisites, mutation risks, retry behavior, Supervisor limitations, and even a Claude Desktop-specific timeout workaround. Because an output schema exists, it does not need to explain return values in detail.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents the individual parameters thoroughly. The description still adds useful cross-parameter semantics: exactly one mode must be selected, `options` merges top-level keys and one nested level, and deeper nested mappings are replaced rather than merged.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: managing Home Assistant apps/add-ons and proxying app APIs. It also distinguishes this tool from the sibling `ha_get_app` by directing inventory/status/metadata reads there first, so an agent can tell the tools apart without opening both schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives explicit routing rules: use `ha_get_app` first for inventory/status/metadata, use proxy mode only for documented app-specific read APIs, and do not infer private schemas. It also specifies that exactly one mode must be used and explains the prerequisites and constraints for each mode.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools