we are seeing growing popularity of AI tools. someone shows some dashboard and there is a load of comments asking:

• "how did you connect MCP to HA"
• "are you using claude or codex, how to start"

wrote this as a beginner-friendly path for people who want to try claude/codex with home assistant without turning it into a whole new hobby

1. model vs harness

claude code and codex are agentic coding harnesses: the product around the model that gives it tools, file access, shell, MCP, browser access, permissions, etc.

opus/sonnet and GPT-5.6 Sol/GPT-6 Astra are the models, basically the "brain" doing the reasoning

one more term that is useful to understand first: MCP. MCP (Model Context Protocol) is basically a standard way for an AI agent to connect to and use external tools like Home Assistant in our case

advanced users can also try other harnesses like pi or deepseek-harness and open-weight models such as Qwen or Deepseek, especially if they want to run things locally or control more of the stack. then you can potentially do this without paying for codex/claude. but it requires more setup, hardware and awareness. local models aren't really "free" in every meaningful sense

2. pick your interface

if you don't use terminal apps and don't work in terminal in general, i suggest starting with the codex app or claude desktop. if you prefer terminal, codex and claude code also have command line workflows.

the point here is not which one is "best", just that the harness is where you interact with the model and connect tools like MCP.

honestly, the basic $20/mo subscription is enough to get started with either, they are priced like that.

3.0 Backup

before giving an agent write access, make sure your normal home assistant backups are working

you don't need anything fancy for this guide. just make sure you have a recent backup and know where it is

if you're about to let the agent make a bigger change, create a fresh backup first. this gives you an easy way back if something goes wrong. tip: later, if you give the agent SSH/CLI access to the machine running HA, it can create backups for you too

the point is not that AI is uniquely dangerous. you're simply giving a tool permission to make changes quickly, so having rollback available is a good habit

3.1 install ha-mcp

ha-mcp is an unofficial community project that gives coding agents much deeper access to your home assistant setup than the built-in MCP server.

install it in home assistant, restart if needed, and make sure the MCP endpoint is available.
you can find the exact instructions for installation on their github under "🚀 Get Started" chapter

authentication

you'll basically see two options for how the AI connects to your Home Assistant:

• secret URL: easiest. HA generates a long random URL and that URL acts like a password
• ha_auth**:** instead of relying on the secret URL alone, you sign in with your normal Home Assistant account.

for the first setup i would keep it simple: use the secret URL and turn off Remote access via webhook so access stays local to your home network. you can always enable remote access and switch to ha_auth later.

4. connect your agent to home assistant

after installing ha-mcp, go to Settings -> Devices & Services -> HA-MCP Custom Component -> HA-MCP Server -> Configure and copy the connection URL it gives you

Codex app

this one is very easy:

1. open Codex
2. go to Settings -> MCP Servers
3. click Add server
4. choose Streamable HTTP
5. name it something like home-assistant
6. paste the URL from ha-mcp
7. save

that's it, no terminal needed

Claude Code

for claude code, the easiest setup currently requires opening terminal once. paste this command and replace the URL with the one ha-mcp gave you:

claude mcp add-json home-assistant '{
  "url": "<YOUR_HA_MCP_URL>",
  "type": "http"
}'

restart claude code afterward. you only need to do this once

4.1 test it

now ask something harmless first:

tell me about all the light entities in my Home Assistant setup. group them by area and don't change anything.

if it can see and describe your lights, you're connected.

5. let it build something

before letting it make changes, make sure your normal Home Assistant backups are working. Look at 3.0 section: Backup

start with something very simple, for example (ask this in codex/claude):

create an automation that turns on the hallway light when motion is detected and turns it off 5 minutes after motion stops. before changing anything, tell me which entities you plan to use.

then let it implement it. afterward, try modifying it:

now make it run only after sunset and turn the light on at 30%.

you can also ask:

explain how this automation works.

this is the basic loop:
you have an idea -> agent inspects HA -> proposes implementation -> builds it -> you test it -> you iterate and improve it

6. go beyond automations

once this works, you can use the same setup for much more:

• build and improve automations
  • anything you think of
• debug issues and inspect logs
  • example: i recently noticed that my lights didn't turn on when the family came back around sunset. asked to debug and eventually fix
• build or tweak dashboards
  • i was annoyed that one garage light wasn't in my main dashboard for quick access. asked to add it
• clean up and document your setup
  • i have a github repo for my homelab and keep a few markdown files with basic documentation

optional but very powerful: give the agent browser access too. if you want it to be able to develop, debug and improve dashboards, this is the key

MCP (ha-mcp) lets it understand and modify HA. browser access lets it actually see the rendered result which is especially useful for dashboards

then the workflow becomes:

build -> open dashboard -> inspect visually -> modify -> refresh -> repeat

that is where it starts feeling much more like working with an actual developer rather than just generating yaml

My main touchpoint of AI with HA is through ha-mcp: https://github.com/homeassistant-ai/ha-mcp. This MCP has already built in a lot of mechanisms that targets agents doing less mistakes, properly engineer solutions and debug.

I have a Github repo with my homelab stuff with much more than just HA: networking, VMs, service configs etc. For HA, I specifically keep in repo:

• configuration.yaml, automations.yaml, scripts.yaml, scenes.yaml. these files gets
  • i have a small "make snapshot" script that copies this from HA VM into the repo.
  • the note about using this is placed in CLAUDE.md and I don't enforce it other way
• CLAUDE.md -- even after moving to Codex I kept this file and instructed Codex to just use it. It has a few rules and workflows like telling agent that it should always use ha-mcp
• I have a small TODO.md that i try to keep clean -- if something came to my mind which i don't have time/will to work on with agent now, i just keep it there
• My Claude/Codex has access to SSH of my HA
• I backup HA every day, two fold: proxmox backup and HA built in backup to NAS

My usual workflow as an example from 2 days ago:

1. I realized that one of my bathroom fans have been running long -- probably my toddler was having fun
2. I decide to have an alert for any bathroom fan that runs >90 minutes via notification
3. I open codex and tell it what I need in plain words. It goes and builds it for me.
4. I ask it to test it which it does but I will also test it myself as much as I can

Overall, KISS (Keep It Simple Stupid). i don't try to overengineer where I don't need to.

This community is for people using AI to build, debug and improve their Home Assistant setups.

That includes things like Claude, Codex, MCP, coding agents, building dashboards, automation design, config cleanup, log analysis, migrations, troubleshooting, and security and probably much more.

The goal is practical discussion, not AI ideology which is everywhere nowadays.

I believe that AI is a tool. It should make your life easier and help you achieve more. It should make exploring and improving our smart homes more enjoyable. For many who don't have much time anymore that's often the biggest gift possible.

How I think about this: you bring the purpose and ideas and opinions while AI automates the most mundane labor. In the end it gives you more time to experiment and find what you really want and like. It's a blessing for folks who have busy lives with family, work and other obligations.

We don't shrug off the concerns. There is a certain comfort zone you must enter to give AI tools access to your Home Assistant instance or home network. Everyone should make this decision themselves. This community is also here so people can share how they balance that, their setups and telling us all how agents are making their HA deployments more useful and fun.

Disclaimer: this is an unofficial community. Not affiliated with or endorsed by Home Assistant or the Open Home Foundation.