Skip to content

# HA-MCP Settings

Language
Theme
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)

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

No tools currently security-gated. Enable per-tool gating from the Tools tab.

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.

Your browser is blocking site storage; choices apply for this session only.

## Theme

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

Theme preset Aa Dark Aa Light Auto Aa Paper Aa Gray Aa High Contrast

## Text size

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

Text size 100% 115% 130% 150%

## Custom colors

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

Background Text Accent

The chosen background and text colors fall below a 4.5:1 contrast ratio and may be hard to read together.

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.

Enable entity visibility filter

## Enforce mode

Extends the filter from decluttering search and overview to every tool read. A direct read of a hidden entity returns “not found”, and a content read (dashboard, template, automation, trace, log, or file) that would surface a hidden entity is refused. Best-effort concealment against incidental exposure, not a hardened security boundary.

Make hidden entities unreadable across all tools (not just search)

## Hide by category

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

Entity categories to hide Diagnostic Config Also entities already hidden in Home Assistant

## Hide by area or label

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

Areas Labels

## Hide specific entities

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

Denied entity IDs

## 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 areas Allowed labels

Allowed entity IDs, one per line.

Allowed entity IDs

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

Only show entities exposed to Assist