Skip to content

# HA-MCP Settings

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)

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.