Agent API & MCP — Security Review

Review findings — September 2026

Both issues below were found in our own review of newly written code, before release and before any customer could reach them. Neither was ever live. They are published for the same reason as the ones below: a security page that lists only successes is not evidence of much.

Finding 4 Device credentials were readable with read-only access Resolved

Severity: moderate — over-broad credential exposure within a single account. No cross-account exposure, and never released.

Work to let an agent edit ESPHome device configurations treated every file in that folder alike. One of them, secrets.yaml, is not a device configuration at all: it holds what every device authenticates with — the wifi password, the API encryption keys, the firmware-update passwords. A token holding nothing but read access could therefore have retrieved the credentials for a whole fleet of devices, and one with edit access could have replaced them. Device configurations refer to secrets by name and never by value, so nothing legitimate needed to read them. That file is now refused on both read and write, in the portal and again on the component running in your home.

Finding 5 A build's identifier was treated as authority on its own Resolved

Severity: moderate — would have allowed limited cross-account exposure of build output. Never released.

Firmware builds run for minutes, so they are tracked as jobs the caller polls for output. Ownership of the Home Assistant instance was checked on every poll, but the job identifier itself was then accepted unqualified — so someone who came by another user's job identifier could have read that build's output, or cancelled the installation, through an instance of their own. The identifiers are random and unguessable, but that is obscurity rather than access control, and they are handed to callers and recorded in audit trails. The owning instance now travels with every poll and cancellation, and a mismatch is indistinguishable from a job that does not exist.

Review findings — August 2026

All three issues below were found during the review of the hosted endpoint, before it had any real usage, and all three are fixed. They are published because a security page that lists only successes is not evidence of much.

Finding 1 Shared request quota across hosted users Resolved

Severity: low — availability only. No impact on confidentiality or integrity; permissions and audit logging were unaffected throughout.

Request quotas were enforced per client network address. When the MCP server moved from running on each user's own machine to being hosted by us, every user's brokered calls began arriving from a single address and therefore shared one quota — so a single busy agent could have exhausted it for other users. Quotas for token-authenticated internal traffic are now keyed on the token itself, giving each user their own. Public traffic is still keyed per address, so the change cannot be used to escape a quota.

Finding 2 Deployment could silently drop web-server routes Resolved

Severity: low — availability only, no exposure of data or bypass of access control.

Our deployment regenerates the web-server configuration from a template. Any route added by hand outside that template was therefore removed by the next deployment. This affected the new agent endpoint and, more importantly, revealed a pre-existing latent fault in the off-site backup upload route, which had the same weakness and would have been dropped by any deployment. Both routes are now produced by the template itself, so they cannot drift out again.

Finding 3 Read access was account-wide, not per instance Resolved

Severity: moderate — over-broad read access within a single account. No cross-account exposure: a token could only ever reach Home Assistant instances belonging to its own owner, and write protection was never affected.

Ticking instances when creating a key granted write access to those instances, but read access was a single account-wide permission. Every key could therefore read every Home Assistant on its owner's account — states, entities, automations and logs — including instances deliberately left unticked. Two things combined to cause it: reads were checked account-wide rather than per instance, and a key created with no explicit account-wide permissions fell back to a default that included the read wildcard. Reads are now granted and enforced per instance, and an ungranted instance is invisible to the key rather than readable. Reported by a customer who noticed an agent reading an instance they had not given it.

Known limitations

Current, accepted trade-offs. We would rather state them than have you discover them.

• Tokens issued before August 2026 can still read everything. They hold an account-wide read scope, which is honoured as an all-instances wildcard so they keep working. Only newly issued tokens get per-instance read gating. If you minted a key before this change and want it limited to specific instances, re-save its permissions on the API tokens page, or revoke and re-issue it.
• Authentication is a bearer token, not OAuth. The Model Context Protocol specification expects remote servers to implement OAuth 2.1. We do not yet. In practice this means your token sits in a configuration file on your own machine, in plain text, with the same handling requirements as any other API key — protect the file, and revoke the token if you suspect exposure. Adding OAuth is on the roadmap; it requires an authorisation server and a consent flow for choosing which instances a client may reach, so it is a substantial piece of work rather than a quick change.
• A bad firmware build can take a device offline. Installing firmware is a physical act, and a device that accepts a broken build may need to be reached with a cable to recover. ESPHome's own safe-mode and bootloader rollback usually prevent that, and the build has to succeed before anything is installed, but the risk is not zero. This is why installing is gated on the edit permission rather than the control one: a token that can only call services cannot flash anything.
• Device logs contain your wireless network name. An ESPHome device prints its wifi SSID and access-point address in its own startup log. The dashboard hides them visually, but that is a display effect, not redaction — anything reading the log stream, including an agent with read access, sees them. They are not credentials, and the password is never printed, but a read-only token does learn which network the device is on.
• Tokens do not expire by default. They remain valid until you revoke them. Set an expiry when creating one if that suits your use better.
• Session state is held in memory. A restart of the service ends open sessions; clients reconnect automatically. It also means the endpoint runs as a single process, which is a capacity consideration rather than a security one.
• The sensitive-domain list is a block list. Anything not on it is permitted once write access is granted. A newly invented integration category would not be blocked until the list is updated.
• Audit logging is best-effort. It is designed never to break the request it records, so a database failure could in principle lose an entry rather than refuse the call.
• An agent with write access can act. No amount of scoping changes the fact that granting ha:write lets an AI agent turn things on and off in your home. Grant the narrowest scope that does the job.