Connect an AI client

Claude Code works directly. Claude's hosted custom connector can reach Phoenix in two ways: directly with an access key, when your organization has Anthropic's limited Request headers beta, or through Home Assistant's MCP Server integration on Home Assistant 2026.10 or later. Neither is in the panel's normal client chooser.

• Claude now uses one hosted remote-connector system across the web app, Desktop, mobile apps, and Cowork. Connections originate from Anthropic's cloud, so the MCP endpoint must be public.
• Personal plans add connectors under Customize > Connectors. Team and Enterprise owners add them for the organization before members connect.
• Users can control connector access and individual tool permissions.
• Request header authentication is a limited organization beta. Choose Authentication: No sign-in first, then pick authorization from the header-name list and enter the full value Bearer phx_your_access_key_here. The list offers authorization only with No sign-in; entering it as a custom header name needs Anthropic's approval. Dialog layouts vary; some show authentication fields under Advanced.
• The connector URL is your public Home Assistant address followed by /api/phoenix-mcp. Any proxy or tunnel in front of Home Assistant must pass streamed responses through; a Cloudflare quick tunnel, for example, does not.
• The access key is shared by everyone in the organization who uses the connector. Create a dedicated least-privilege Phoenix access key for this connector.
• Do not put the access key in the connector URL. Claude sends request-header values exactly as entered and does not add the Bearer prefix for you.

Through Home Assistant's MCP Server

Without the Request headers beta, Claude can sign in to Home Assistant itself and reach Phoenix's Assist tools through Home Assistant's own MCP Server integration. This needs Home Assistant 2026.10 or later, reachable over public HTTPS. Behind a reverse proxy or tunnel, open Settings > System > Network, turn on Trust X-Forwarded-For, add the proxy's network under Trusted proxies, and set the external URL to the public address.

1. In the Phoenix MCP panel, open Settings > Assist Tool Provider and bind a least-privilege access key. Claude uses this key.
2. In Home Assistant, add the Model Context Protocol Server integration. In its options, turn off Expose all LLM APIs, set Control Home Assistant to only Phoenix MCP (scoped), and keep Require an administrator account on.
3. In Claude, add a custom connector with the URL https://your-home-assistant/api/mcp/phoenix_mcp. Keep the sign-in authentication, choose Claude's published identity for the OAuth client, and leave any client ID and secret empty.
4. Connect and sign in with a Home Assistant administrator account.

• Claude holds a Home Assistant administrator credential. Selecting the Phoenix API limits the tools Claude is offered, not what the credential can do in Home Assistant's own API.
• The Phoenix kill switch and revoking the bound access key stop Phoenix's tools but do not revoke Claude's Home Assistant sign-in. Disconnecting the connector in Claude does not revoke it either: delete its refresh tokens in your Home Assistant profile under Security, where each sign-in appears separately.
• Everyone using the connector shares the Assist-bound access key, and changing that binding also changes what Assist voice uses. Phoenix's per-key request limits do not apply on this route.
• Home Assistant publishes each tool's fields and required list but drops rules stated for the tool as a whole, such as "give at least one of these". Phoenix still checks every call against its full rules and refuses one that breaks them. Confirm-gated actions return queued_for_approval for an administrator to review.
• Home Assistant describes the whole instance, not the MCP URL, as the protected resource. Claude accepted this in testing, but it differs from Claude's published requirement and may change.

See Anthropic's remote connector setup and connector authentication documentation, and Home Assistant's MCP Server integration.

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

For another native skill client, use its destination from this table with the same mkdir -p and curl -fsSL pattern. The guide is generic and contains no access key or entity data.

For Cursor, download the guide to .cursor/phoenix.md and add .cursor/rules/phoenix.mdc with the metadata below. The panel supplies the complete command. A plain .md file in .cursor/rules is ignored.

---
description: Use when inspecting, controlling, or configuring Home Assistant through Phoenix MCP
alwaysApply: false
---
Before using Phoenix MCP tools, read @.cursor/phoenix.md for scoped permissions, approvals, and MESA guidance.

See Codex skills, Gemini skills, and Cursor rules. For other clients, reference the downloaded guide from their supported project instructions.

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 access key'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.

Assist and Voice also check the requesting Home Assistant user. Active administrators can use the access key's privileged tools. Other users and unidentified satellites can use scoped household controls and discovery, with the access key's existing Confirm and MESA gates. Identified users retain their Home Assistant entity permissions. Logs, configuration, templates, diagnostics and authoring require administrator identity, even with a pass-through access key. The Voice Assistant preset denies System log read by default. Removing or changing a user invalidates an active request; approving a queued household action still checks its original requester.

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 2026.7 or later, which is also the integration's own minimum.

1. In the Phoenix MCP panel, open Settings > Assist Tool Provider and choose the Bound access key. Only one access key can be bound at a time; a least-privilege access key (for example the Voice Assistant persona) is recommended. Changing or clearing the binding applies to the next tool call: a conversation turn already running under the previous access key has its further tool calls refused rather than continuing with that key.
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.

With Google Gemini, Home Assistant cannot show some tool fields in their full form, such as a field that takes one entity or a list. Phoenix shows Gemini a simpler form of those tools and still checks every call against the full rules. Free-form settings such as service data or an automation config are sent as JSON text, which Phoenix turns back into the original object. Two tools whose value can be any JSON type, patch_dashboard and set_zigbee_device_property, are not offered to Gemini; use set_dashboard_config or the dashboard card tools instead.

From Home Assistant 2026.10, a refused or failed Phoenix tool call reaches the model marked as an error rather than as a normal answer, and a call queued for approval is not marked as one. Each tool also carries Phoenix's read-only and destructive hints, which Home Assistant's MCP Server integration passes on to its clients. Earlier releases receive the same answers without these markers.

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 an access key, a provider account, and a model.
2. Choose its Conversation style and Detail. Optionally enable Home-focused, a focus preference rather than a security control. The next request uses any changed setting immediately.
3. 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.
4. Prefer to do it by hand? In Settings > Voice assistants, set your assistant's conversation agent to Phoenix MCP.

Optional command routing can handle supported Voice commands locally or through a separate decision account before using your conversational provider. It defaults to Off. Routing follows the Assist conversation language and installed Assist language catalog; supported sentences and model accuracy vary by language. Keep Home Assistant's Prefer handling commands locally disabled so commands reach Phoenix and its permission checks.

When the model marks a Home-focused voice refusal using Phoenix's private protocol, Phoenix replaces the model prose with a localized refusal. There is no spoken override: Home focus stays on until you turn it off in settings. The rejected utterance is not retained. A model that omits the private marker is handled normally without Phoenix guessing from its prose. Even at Detailed, Voice keeps replies suitable for speaking aloud.

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 an access key's scope, so a task reads only what the access key can see and every tool call it makes is gated, MESA-checked, and audited like any other. Available on every supported Home Assistant version. 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.

AI Task always uses household-only authority, including when an administrator starts it. It cannot use privileged tools such as logs, configuration or authoring. Use it for scoped home state and control; use administrator Agent Chat for maintenance tasks. See the security boundaries.

1. In Settings > AI Task (the Phoenix MCP panel), enable it and pick an access key, 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. Choose a Conversation style and Detail for free-text results. Structured tasks omit both preferences and follow their output schema exactly.
3. 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.
4. 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 access key'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. A reply the structure rejects, such as one with a missing or unrequested field, a value of the wrong type or a value outside its limits, fails the action instead of reaching the automation; any tool calls the task made before that have already run. Conversation style and Detail are omitted for this structured path so presentation preferences cannot compete with the schema.