Ensure the MQTT integration is configured in Home Assistant and connected to your MQTT broker; MQTT discovery is enabled by default with the homeassistant prefix
From your device firmware or gateway, publish a discovery config message to homeassistant/<component>/<object_id>/config as a retained JSON payload; include at minimum: name, unique_id, state_topic, and device block with identifiers
Use abbreviated keys supported by Home Assistant (e.g., stat_t for state_topic, cmd_t for command_topic, uniq_id for unique_id) to keep payloads compact
Publish current device state to the state_topic; Home Assistant will subscribe automatically after processing the discovery message
For devices with multiple entities (sensors, switches, etc.), publish a separate discovery config for each entity under the same device block using shared identifiers so they are grouped under one device in the UI
To remove a device, publish an empty retained payload to its config topic; Home Assistant will remove the entity
Known gotchas
Discovery config messages must be retained (MQTT retain=true); otherwise Home Assistant misses them after a restart and the device disappears from the UI
The unique_id field is required to enable entity customization and deduplication across restarts; devices without it cannot be edited from the UI
Home Assistant validates the component type in the topic path (e.g., sensor, switch, light); an unrecognized type causes the message to be silently ignored
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp