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.
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)

Developer

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.
Let AI agents edit these policies (ha_manage_security_policy)
Registers the ha_manage_security_policy tool, which reads and replaces the policy document this tab edits. Off by default. Independent of the master switch above: this controls who can edit the rules, not whether they are enforced. The tool does not expose pending-approval queue operations, but a policy-gated set action can still require approval.
Enabling this lets connected AI agents rewrite the security policies on this tab, including removing approval gates. To keep a human in the loop, gate the tool BEFORE you enable it: on the Tools tab, switch on "security gated" for Manage Security Policy. That rule can be authored while the tool is still off, and it enforces once the master switch above is on and the server has restarted. Restart the App (add-on) after toggling either switch.
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.
Allow approve/deny from Home Assistant events
Off by default. While on, an ha_mcp_approval_response event carrying a pending request's token, a decision and the PIN below decides that request — so your own notification automation can approve it from a phone. Needs a PIN before it can be switched on.
An AI agent with enough access can guess or obtain this PIN — by asking you for it, or by writing an automation that reads it out of a response event — and then approve its own requests. Home Assistant cannot tell an event fired by your automation from one fired by an agent, so the PIN is the only thing between them. Switching this on accepts that limitation. Deciding in the Pending list is unaffected — on the settings UI the server itself serves. The stdio sidecar's settings page sets the PIN and the policy, but cannot list or decide pending approvals: those live in the server process it cannot reach.
Approval PIN
At least 4 characters. Stored as a salted hash and never shown again, and kept out of the policy document so nothing that reads or writes policy carries it. Five wrong PINs within five minutes close the channel for the rest of that window — the Pending list on the server's own settings UI keeps working (the stdio sidecar page cannot show it).

Pending approvals

No pending approvals.

Gated tools

Policies apply to individual tools. Other tools may perform the same action. For example, requiring approval for ha_call_event does not restrict event firing through ha_call_service.

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 can occasionally move to a new port). 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.

Without enforce mode (below), this is 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 the filter alone as a security boundary.

Enforce mode

Extends the filter from decluttering search and overview to every tool read except ha_report_issue by default. A direct read of a hidden entity returns “not found”, and a content read that would surface one is refused. The report-tool exception is controlled below. Best-effort concealment against incidental exposure, not a hardened security boundary.

While this is off, ha_report_issue and all of its diagnostic output—including logs—stay outside enforce mode on every call, even when visibility data is healthy or unavailable. Turn it on to scan and refuse that tool like other reads.

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, nonmatching entities are hidden (including entities added later). A match overrides category, Home Assistant hidden-state, and Assist filters; denied entity IDs and excluded areas or labels still win. 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. Not applied while an allowlist is active; otherwise adds two websocket reads per search.