Give your AI agent the keys to exactly what it needs.
Create one scoped token for each AI agent. Choose what it can read, what it can control, and which actions need approval. Use Agent Chat inside Home Assistant or connect any MCP client.
Choose how you want to chat
Use Agent Chat inside Home Assistant for the shortest setup, or connect an external MCP client. Both options use the same token scope, approvals, audit log, and MESA rules.
Use Agent Chat
A floating chat window with a token switcher, inline Approve/Reject for gated actions, and per-provider model and thinking controls.
Agent Chat ExternalConnect a client
Point Claude Code, Cursor, Codex, Gemini CLI, or another bearer-token-compatible MCP client at Phoenix MCP's endpoint.
Connect an AI clientWhy Phoenix MCP instead of a long-lived access token
A long-lived access token (LLAT) plus the native MCP server gives every client the same all-or-nothing view of your home. Phoenix MCP keeps the same tools and adds the control layer that the native system has no place for.
| Capability | LLAT + native MCP | Phoenix MCP token |
|---|---|---|
| MCP tool compatibility | 23 native tools | Same 23 tools, identical names and responses, plus 137 more tools |
| Entity filtering | Binary: expose or hide, same for all clients | Four permission states, per token |
| Per-client control | No, all clients share one exposed set | Yes, independent permissions per token |
| Read-only access | No | Yes, READ allows reads and blocks writes |
| Audit trail | None | Request logging with outcome and entity, on by default and configurable per outcome |
| Rate limiting | None | Per token, configurable |
| Expiry | None | Optional, auto-archived on expiry |
| Revocation | Revoke the LLAT on the HA profile page | Instant; the token's next request is rejected |
| Sensitive attribute scrubbing | None | Always applied |
| Client reconfiguration | /api/mcp with an LLAT | /api/phoenix-mcp with a phx_ token (same tools; swap the URL and the bearer value) |
If you are connecting Claude Code, Cursor, Codex, Antigravity, or another compatible AI tool to Home Assistant, Phoenix MCP gives you control the native system cannot.
Three layers between an agent and your home
Every action passes three checks: entity permission, capability, then MESA safety. Phoenix runs the action only when all three allow it. Reads use the permission checks that apply to them.
The permission tree
Domains, devices, and entities, each set to read-write, read-only, deny, or inherit. A two-pass resolver decides what every request can touch.
PermissionsCapability flags
29 opt-in switches gate the high-impact operations: restart, physical control, writing automations, reading logs, editing YAML. Off by default.
CapabilitiesSemantic safety profiles
MESA stores a semantic profile for each entity: what it is, how sensitive it is, and how it should be treated by your AI agent, not just allow or deny. Describe your home's nature once, and every agent inherits the safe treatment: a lock or camera stays read-only or confirmation-only because of what it is, no matter which token is asking.
MESA