Quick start

Open the panel and launch the guided setup

Open the Phoenix MCP panel from your Home Assistant sidebar. On the Access keys tab, start the guided setup ("Connect your first AI agent"). The wizard takes you from an empty access key to a working agent without leaving the panel.

Pick a persona

A persona is a named preset that sets every capability at once: what the agent may read, what it may control, and what needs your approval. New user is preselected and is a safe starting point. It lets the agent read your home and control the devices you grant, while locks, alarms, covers, and valves ask for your confirmation.

Choosing a persona modifies the entire capability set, not just a label; you can fine-tune any single capability later. The personas are described on Capabilities.

Name the test access key

The wizard suggests my_access_key as an example; change it if you like, and set an optional expiry. The expiry is fixed once the access key is created, so set it here if you want one; the name can be changed later from the access key's detail page.

Grant access to one entity

The wizard highlights your light domain. Expand it, find a light you can physically see, and click the W button on that row to grant full read and write access; its badge changes to "WRITE". Granting one entity is enough to prove the connection; you can grant more later from the access key's detail page.

Choose how to connect

You can chat with your agent entirely inside Home Assistant using an API key or local hostname from your model provider, or connect an external app instead. Pick whichever fits:

Set up your model provider

Pick a provider you have already added, or add a new one: choose from the dropdown and click Add new provider…. Paste an API key (or, for a local Ollama server, its URL) and click Validate. Validating only tests the connection and lists its models; nothing is saved until you continue. Once validated, pick a default model.

Try it

Click Try now. The wizard opens the Agent Chat window with your new access key and the provider and model you just set up already selected, and a test question typed in for you: "How many lights are in my home?" Press Send. The wizard closes as soon as you send your first prompt, so you land in a normal chat with your new agent.

Connect your agent

The wizard shows a ready-to-paste command for your agent, plus the raw access key value; both are shown once here.

Claude Code, for example, uses a single command line; substitute your Home Assistant address. Each client has its own command or configuration format. The panel shows the form for each supported client, including DeepSeek Harness, and Connect an AI client explains the file locations, environment variables, and verification steps. If you are not ready to connect an agent yet, Connect later skips straight to the end; the access key is already created and waiting on the access key page.

Run a test

Ask your agent to do something simple, like "List my Home Assistant lights". The moment it calls Phoenix MCP, the wizard detects the connection and confirms it. That is the whole loop: a scoped access key, connected and verified.