Set Integration
ha_set_integrationAdd, enable/disable, update options, or reconfigure Home Assistant integrations using the integration's own config flow.
Instructions
Manage an integration (config entry): enable/disable, add, update options, or reconfigure.
Modes (pick one):
Enable/disable: entry_id + enabled.
Add integration: domain (+ config) — drives the domain's config flow, including menus and multi-step forms.
Update options: entry_id + config — drives the entry's options flow (what the "Configure" button does in the HA UI). Like that dialog it is a patch: omitted fields keep their current values, and a field set to null is cleared where the integration's schema allows that field to be empty.
Reconfigure: entry_id + reconfigure=True + config — drives the existing entry's official reconfigure flow (host, port, credentials). Call it without confirm_token for a read-only preflight; repeat with the token it returns to apply.
WHEN NOT TO USE:
Helpers (template, group, utility_meter, ...): use ha_config_set_helper. The exception is
otp, which is a helper in the HA UI but is created HERE via domain="otp" — its flow needs a live TOTP code, so ha_config_set_helper deliberately omits it.Config subentries: use ha_config_set_helper(helper_type='config_subentry').
Removing an entry: use ha_remove_helpers_integrations.
Use ha_get_integration() to find entry IDs, and ha_get_integration(entry_id=..., include_schema=True) to inspect the options fields before an update. Its supports_reconfigure field tells you whether an entry qualifies for reconfigure=True; only integrations implementing async_step_reconfigure do.
Caveats: adding an integration runs its config flow exactly as the HA UI would (may pair devices, scan the network, create entities). Flows requiring a browser step (OAuth) or an asynchronous provider step error out at that step with a structured error instead of completing. Reconfigure edits the settings a live integration connects with: a wrong host or credential takes it offline, and there is no automatic rollback — the returned rollback metadata describes repeating the official flow by hand with the previous values, which this tool cannot read back. The preflight does not validate config keys against the integration's form; wrong field names surface on the confirm call.
EXAMPLES:
Disable: ha_set_integration(entry_id="abc123", enabled=False)
Add: ha_set_integration(domain="workday", config={"name": "Workday"})
Update options: ha_set_integration(entry_id="abc123", config={"scan_interval": 30})
Reconfigure preflight: ha_set_integration(entry_id="abc123", reconfigure=True, config={"host": "10.0.0.5"})
Reconfigure apply: repeat that call adding confirm_token="sha256:..."
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| config | No | Flow form data. With 'domain': input for the new integration's config flow. With 'entry_id' alone: input for the entry's options flow (updates its options). Updating an existing entry — options or reconfigure — is a patch: a field you omit keeps its current value, and a field set to null is cleared where the integration's schema allows that field to be empty. Multi-step flows consume keys per step. A field two steps declare gets your one value both times; pass step_values={'<step_id>': {'<field>': <value>}} to give a step its own value, or to leave the field out of that step; a LIST of those objects supplies one per encounter when the flow presents a step more than once. Menu steps take 'next_step_id' — a string, or a list of successive selections for flows that present more than one menu (e.g. a menu revisited after each branch, ending in a finish option). The step's data_schema is returned on validation errors so field names can be corrected. | |
| domain | No | Integration domain to add (e.g. 'workday', 'local_calendar') — starts and drives that domain's config flow. Pass the flow's form fields in 'config'. | |
| enabled | No | True to enable, False to disable the entry. Requires entry_id; mutually exclusive with 'domain' and 'config'. | |
| entry_id | No | Config entry ID of an existing integration (enable/disable and options-update modes). Omit when adding via 'domain'. | |
| reconfigure | No | Use the existing config entry's official reconfigure flow (its connection settings) instead of its options flow. Without confirm_token this is a read-only preflight that returns one. | |
| expected_mac | No | Requires reconfigure=True. MAC or IEEE the entry's device must still report. | |
| confirm_token | No | Requires reconfigure=True. A token from a reconfigure preflight; applies the change. Any token still matching the entry's current state and the same requested config is accepted, so a token stays valid while nothing moves. | |
| expected_device_id | No | Requires reconfigure=True. Device registry ID the entry must still own, before and after the change. | |
| expected_unique_id | No | Requires reconfigure=True, AND the ha_mcp_tools custom component: Home Assistant does not expose a config entry's unique_id over its API. Without the component this is rejected — anchor on expected_device_id, expected_mac or expected_entity_ids instead. | |
| expected_entity_ids | No | Requires reconfigure=True. Exact entity IDs that must remain associated with the entry. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||