Give your AI agent the keys to exactly what it needs.
Create one scoped access key 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 access key scope, approvals, audit log, and MESA rules.
Use Agent Chat
A floating chat window with an access key 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 MCP client that supports bearer authentication at Phoenix MCP's endpoint.
Connect an AI clientWhy Phoenix MCP instead of a long-lived access token
The gateway and permission checks run inside Home Assistant. Agent Chat, Voice, AI Task, Home Companion and decision routing can send requests and scoped results to a configured hosted provider. Choose a local provider when you need local model processing. This documentation site also loads Google Fonts.
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 access key |
|---|---|---|
| MCP tool compatibility | 23 native tools | Same 23 native operations with stable domain-prefixed names and permission-scoped responses, plus 146 additional tools |
| Entity filtering | Binary: expose or hide, same for all clients | Four permission states, per access key |
| Per-client control | No, all clients share one exposed set | Yes, independent permissions per access key |
| 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 access key, configurable |
| Expiry | None | Optional, auto-archived on expiry |
| Revocation | Revoke the LLAT on the HA profile page | Instant; the access key's next request is rejected |
| Sensitive attribute scrubbing | None | Always applied |
| Client reconfiguration | /api/mcp with an LLAT | /api/phoenix-mcp with a phx_ access key (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
30 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 an entity's restrictions once so they apply across access keys. Advisory is the default: most restrictions warn rather than block until you enforce them.
MESA