Connect an AI client

The five steps

claude mcp add --transport http phx-claude-code \
  http://your-ha-address:8123/api/phoenix-mcp \
  --header "Authorization: Bearer phx_your_token_here"

claude mcp add --transport http phx-claude-code \
  https://your-instance.ui.nabu.casa/api/phoenix-mcp \
  --header "Authorization: Bearer phx_your_token_here"

The agent skill

The skill is a usage guide for the connected AI. You get it two ways, and you do not have to choose; the primer always ships, the installed skill is extra.

mkdir -p ~/.claude/skills/phoenix && \
  curl -fsSL http://your-ha-address:8123/api/phoenix-mcp/skill \
  -o ~/.claude/skills/phoenix/SKILL.md

Other agents (Cursor, Codex, Gemini CLI, and so on) download the same guide and reference it from their project rules or context file; the panel shows the exact path per agent. The guide is generic and contains no token or entity data.

Use with Home Assistant Assist and voice

Besides external MCP clients and Agent Chat, you can put Phoenix MCP behind Home Assistant's own Assist, so a voice or chat conversation runs through one token's scope, MESA safety, approvals, and audit instead of the unscoped default assistant. There are two ways to do this; pick whichever fits. For generating data inside automations rather than driving a conversation, see AI Task below.

Option A: bring your own model

Phoenix MCP registers a control API named Phoenix MCP (scoped) that hands its scoped tools to a model an LLM conversation integration already supplies (OpenAI, Google, Anthropic, Ollama, and so on). Requires Home Assistant 2025.2 or later (the core integration itself runs on 2024.5+; the panel disables this card on older versions).

1. In the Phoenix MCP panel, open Settings > Assist Tool Provider and choose the Bound token. Only one token can be bound at a time; a least-privilege token (for example the Voice Assistant persona) is recommended.
2. In your LLM conversation integration (Settings > Devices & Services), set its Control Home Assistant option to Phoenix MCP (scoped), then select that agent in Settings > Voice assistants. This applies to LLM-backed conversation agents, not the default template Assist pipeline.

Option B: let Phoenix MCP be the agent (no external software)

If you would rather not install a separate LLM app, Phoenix MCP can register itself as a conversation agent and run its own model, using an existing Agent Chat provider account.

1. In Settings > Voice Agent (the Phoenix MCP panel), enable it and pick a token, a provider account, and a model.
2. Let Phoenix MCP set it up for you: on the first enable it offers to create an Assist assistant pointed at Phoenix MCP (and, if you leave the option on, make it your preferred assistant). Or use Set up Phoenix MCP assistant in that card any time.
3. Prefer to do it by hand? In Settings > Voice assistants, set your assistant's conversation agent to Phoenix MCP.

Generate data in automations with AI Task

Home Assistant's AI Task feature lets an automation, script, or dashboard ask an AI model to produce text or structured data on demand, through the ai_task.generate_data action. Phoenix MCP can be that model: it registers an Phoenix MCP AI Task entity that runs Phoenix MCP's own model on a token's scope, so a task reads only what the token can see and every tool call it makes is gated, MESA-checked, and audited like any other. Requires Home Assistant 2025.7 or later (AI Task shipped then; the panel disables this card on older versions). Like Agent Chat, the model comes from a provider account, so each task's prompt and the tool results the model sees are sent to that provider; use a local Ollama account to keep tasks fully local.

1. In Settings > AI Task (the Phoenix MCP panel), enable it and pick a token, an Agent Chat provider account, and a model. The Phoenix MCP AI Task entity appears once all four are set, and disappears again if you disable it or clear one of them.
2. Optionally click Make default in the AI Task setup section to make Phoenix MCP your default entity for Data generation tasks, so an ai_task.generate_data action that does not name an entity runs through Phoenix MCP. Home Assistant keeps a single default, so the panel confirms before replacing an existing one.
3. Point an AI Task action at the Phoenix MCP AI Task entity by entity_id, or leave the entity unset to use your default.

Here is an example script which asks Phoenix MCP to summarize the home and shows the answer as a notification. Because the task runs Phoenix MCP's scoped tool loop, the model looks up the lights itself, within the token's scope, before it writes the sentence:

sequence:
  - action: ai_task.generate_data
    data:
      task_name: home_summary
      entity_id: ai_task.phoenix_mcp_ai_task
      instructions: >-
        Check how many lights are on and reply with one short,
        friendly sentence naming a few of them.
    response_variable: result
  - action: persistent_notification.create
    data:
      title: Home summary
      message: "{{ result.data }}"

Pass a structure to the action and Phoenix MCP returns a validated JSON object instead of prose (for example { "count": 3, "names": […] }), which an automation can branch on directly.