Connect an AI client

The five steps

claude mcp add --transport http atm-claude-code \
  http://your-ha-address:8123/api/atm/mcp \
  --header "Authorization: Bearer atm_your_token_here"

claude mcp add --transport http atm-claude-code \
  https://your-instance.ui.nabu.casa/api/atm/mcp \
  --header "Authorization: Bearer atm_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/atm-home-assistant && \
  curl -fsSL http://your-ha-address:8123/api/atm/skill \
  -o ~/.claude/skills/atm-home-assistant/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 ATM 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

ATM registers a control API named ATM (scoped) that hands its scoped tools to a model an LLM conversation integration already supplies (OpenAI, Google, Anthropic, Ollama, and so on).

1. In the ATM 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 ATM (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 ATM be the agent (no external software)

If you would rather not install a separate LLM app, ATM 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 ATM panel), enable it and pick a token, a provider account, and a model.
2. Let ATM set it up for you: on the first enable it offers to create an Assist assistant pointed at ATM (and, if you leave the option on, make it your preferred assistant). Or use Set up ATM assistant in that card any time.
3. Prefer to do it by hand? In Settings > Voice assistants, set your assistant's conversation agent to ATM.

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. ATM can be that model: it registers an ATM AI Task entity that runs ATM'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.

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

Here a example script which asks ATM to summarize the home and shows the answer as a notification. Because the task runs ATM'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.atm_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 ATM returns a validated JSON object instead of prose (for example { "count": 3, "names": […] }), which an automation can branch on directly.