Connect an AI client

• 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. In the two-step dialog, choose Authentication: None, add a required Authorization header, and enter the full value Bearer phx_your_token_here.
• The token is shared by everyone in the organization who uses the connector. Create a dedicated least-privilege Phoenix token for this connector.
• Do not put the token in the connector URL. Claude sends request-header values exactly as entered and does not add the Bearer prefix for you.

See Anthropic's remote connector setup and connector authentication documentation.

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

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. 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.

When the model marks a Home-focused voice refusal using Phoenix's private protocol, Phoenix replaces the model prose with a localized refusal and asks you to repeat the complete request and explicitly say to answer anyway. Phoenix recognizes that explicit phrase deterministically in the conversation language (and always accepts the English words answer anyway), bypasses Home focus for that request only, and restores it on the next request. The rejected utterance is not retained. A model that omits the private marker is handled normally without Phoenix guessing from its prose, so weaker models may refuse without giving the recovery instruction. 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 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. 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 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. Conversation style and Detail are omitted for this structured path so presentation preferences cannot compete with the schema.