HA-MCP Custom Component

After setup

• Extra file pathsPaths relative to the config directory, including exact filenames such as sensor.yaml, or paths under /share, /media, and /ssl (read-only on HAOS and Supervised). Each entry is granted read and write for that path and anything below it; enter every path as a separate list item. Entries are matched literally; wildcards such as * are not supported. Traversal and other disallowed paths are dropped.
• Extra YAML write keysTop-level keys ha_config_set_yaml may write in addition to the built-in ones, for YAML-first integrations on this install (e.g. alert2). Trust-boundary keys are dropped.
• MCP server listening portThe port this server listens on. The ha-mcp app (add-on) uses 9583, so this defaults to 9584 to let both run side by side - if you don't run the app (add-on), any free port works.
• Network accessWho can connect to the MCP server port directly. Local network makes it reachable from your local network, with the secret path as the credential, like the app (add-on). This machine only allows connections from the Home Assistant machine itself - the webhook URL and the sidebar panel work either way.
• Authentication modeHow MCP clients prove themselves at the webhook URL. With the secret URL, the link itself is the only credential - OAuth still runs for clients that use it, and a sign-in that returns to an allowed callback URL (see below) is approved automatically: no login and no Client ID or Secret needed. With Home Assistant sign-in, clients such as claude.ai log in with a Home Assistant administrator account (OAuth). With legacy OAuth, this integration runs its own sign-in service and issues a Client ID and Secret to paste into clients that require one - a Home Assistant restart may be needed to fully turn it on or off.
• Legacy OAuth: custom Client ID (optional)Replaces the auto-generated legacy OAuth Client ID. Leave empty to keep the current one. Only used while Authentication mode is set to legacy OAuth.
• Legacy OAuth: custom Client Secret (optional)Replaces the auto-generated legacy OAuth Client Secret. Leave empty to keep the current one. Only used while Authentication mode is set to legacy OAuth.
• Legacy OAuth: regenerate Client ID/Secret nowOne-time action: mints a fresh Client ID and Secret for legacy OAuth mode. It takes effect only after the Home Assistant restart the repair prompt asks for - until you restart, the previous Client ID and Secret keep working and the new ones do not. Also clears the two override fields above.
• Developer: ha-mcp package overrideLeave empty to run the ha-mcp server this component release installed. Only for testing a specific ha-mcp build (a version pin, a pull-request tarball or a wheel URL); applied by reloading the server, without restarting Home Assistant. Clear it to return to the paired server.
• Home Assistant URL (advanced)The URL the in-process server uses to reach your Home Assistant (usually this instance itself). Leave empty to derive it from this instance's port and SSL settings; set a value only when the server needs a different route.
• External URL (optional)Shown as the primary connect URL - use this when Home Assistant sits behind your own domain or reverse proxy. Enter the full base address including the scheme. It must point directly at Home Assistant - opening it in a browser should reach your HA login page - and must not contain a port such as :8123 (or any other port), or remote MCP clients won't be able to reach it. Leave empty to use Nabu Casa / the local address automatically.
• Custom webhook secret (optional)Replaces the random webhook secret in the connect URL (/api/webhook/...). The URL is the credential - use a long, hard-to-guess value. Leave empty to keep the current one.
• Custom direct-access path (optional)Replaces the random path used for direct access on the server port. Same rule: the path is the credential. Leave empty to keep the current one.
• Regenerate connect secrets nowOne-time action: mints a fresh random webhook secret and direct-access path, invalidating the old connect URLs immediately. Also clears the two override fields above.
• Remote access via webhookTurn off for local-only mode: the Home Assistant webhook is not registered at all, so nothing - including Nabu Casa - can reach the server through Home Assistant. The direct server port and the sidebar panel keep working.
• Conversation-agent LLM API
• Conversation-agent tool exposure