HA-MCP Settings

Loading...
⚠ Changes saved. Restart HA-MCP for them to take effect. On next startup, HA-MCP fully removes disabled tools from the MCP tool list. Then reconnect or refresh the MCP server in your AI client (e.g. refresh tool list on claude.ai, re-add/refresh the connector in ChatGPT, or close and reopen Claude Desktop) so it reloads the tool list. Restarting the App (add-on) or Home Assistant does NOT refresh your client's cached tool list.
Server-wide features (Tool Search, YAML config editing, filesystem tools, etc.) appear in both the Server Settings tab and the App (add-on) Configuration page; they're the same settings either way. Either surface stays in sync with the other after the App (add-on) restarts. Changes require HA-MCP to be restarted.
Tools listed in the DISABLED_TOOLS or PINNED_TOOLS env vars are locked read-only; unset the env var to edit them here. Pin toggles only take effect when Tool Search is enabled (Server Settings tab or App (add-on) Configuration page).
Read Only Mode
Turns off all write tools and blocks every tool from making write or destructive calls. Mixed read/write tools (backups, Apps (add-ons), energy preferences, voice pipelines, and code mode when enabled) stay available with their write operations blocked.
Could not read server settings. Read Only Mode status unknown; this view may not reflect what the server enforces.
Settings on this tab save automatically. Changes take effect only after you restart the App (add-on) (applies them server-side) and reconnect or refresh the MCP server in your AI client (reloads the tool list), e.g. refresh tool list on claude.ai, re-add or refresh the connector in ChatGPT, or close and reopen Claude Desktop.

Search & matching

Operations

Tool surface

Diagnostics

Settings UI sidecar

Beta features (dangerous)

Loading backup state…

Tool Security Policies

Per-tool approval gating for high-stakes calls. Use the Tools tab to enable gating for a tool, then refine the matching conditions and approval lifetime here. Condition operators: equals, is one of, regex, contains, is present, greater than, less than.

Global settings

Enable Tool Security Policies
Master switch. Mirrors the toggle in Server Settings. Off by default. Toggle on and restart the App (add-on) to activate the gating middleware. While off, the rules below persist but aren't enforced.
Wait seconds (5-600)
How long the middleware waits for an approval before timing out.
Approval TTL minutes (1-60)
How long a pending approval stays in the queue before expiring.

Pending approvals

No pending approvals.

Gated tools

These settings apply immediately and are saved in this browser and on the server, so they survive restarts in every mode (including stdio, where the settings page moves to a fresh port each session). The docs site offers the same controls in its navigation bar; it has no server and saves per browser.

Theme

One-click color schemes. Auto, the default, follows your OS preference and flips live when it changes.

Text size

Scales the root font size. Browser zoom (Ctrl/Cmd +) still works on top of this.

Custom colors

Pick your own colors on top of the selected theme. Each swatch opens your system's visual color picker.

Hide low-value entities (auto-generated diagnostic or helper entities, or an explicit list) from the collection read tools ha_search and ha_get_overview, so search and overview results are less cluttered. Off by default; changes apply on the next tool call.

Noise reduction, not access control: a hidden entity is still returned by a direct read of its entity_id and still appears in automation, dashboard, and template content. Do not rely on this as a security boundary.

Hide by category

Home Assistant tags auto-generated entities as diagnostic or config.

Hide by area or label

Comma-separated area IDs or label IDs; entities in any listed area or label are hidden.

Hide specific entities

One entity_id per line. These stay hidden even without an entity-registry entry.

Restrict to an allowlist

Advanced: when any allowlist field is set the filter inverts – only entities matching an allowlist stay visible, everything else is hidden (including entities added later). Leave all three empty to disable.

Allowed entity IDs, one per line.

Respect Assist exposure

Hide entities not exposed to Home Assistant's Assist (“conversation”) voice assistant, mirroring the Settings > Voice assistants > Expose list. Adds two websocket reads per search while enabled.