Deployment¶
Deployment Options¶
home-assistant-agent exposes its MCP server (console script home-assistant-mcp) four ways —
local stdio, a loopback-only development listener, a least-privilege container, and a remote
authenticated HTTPS boundary. Pick the row that matches where the server runs relative to your
MCP client, then copy the matching mcp_config.json below. Provider endpoint, credential,
selector, identity, and trust material are supplied at runtime through AgentConfig /
environment variables — replace the <your-…> placeholders and never commit real values into
client JSON or documentation.
| # | Option | Transport | Where it runs | mcp_config.json key |
|---|---|---|---|---|
| 1 | stdio | stdio |
client launches a subprocess | command |
| 2 | Loopback development listener | streamable-http |
a local network port (127.0.0.1 only) | command or url |
| 3 | Least-privilege container | stdio or streamable-http |
Docker / Podman on this host | command or url |
| 4 | Remote authenticated HTTPS endpoint | streamable-http |
a remote host behind a TLS-terminating reverse proxy | url |
1. Installed stdio process¶
The client launches the server over stdio via uvx — best for local IDEs
(Cursor, Claude Desktop, VS Code):
{
"mcpServers": {
"home-assistant-mcp": {
"command": "uvx",
"args": ["--from", "home-assistant-agent", "home-assistant-mcp"],
"env": {
"MCP_TOOL_MODE": "intent",
"HOME_ASSISTANT_URL": "<your-home_assistant_url>",
"HOME_ASSISTANT_TOKEN": "<your-home_assistant_token>"
}
}
}
}
2. Loopback development listener¶
Run the server as a long-lived HTTP process, bound to loopback only:
home-assistant-mcp --transport streamable-http --host 127.0.0.1 --port 8000
curl -s http://localhost:8000/health # {"status":"OK"}
Do not expose this listener beyond loopback. Network deployments require direct TLS
or an explicitly trusted TLS-terminating ingress, configured authentication, an exact
MCP_ALLOWED_HOSTS, and an exact trusted-proxy CIDR policy — see Option 4.
Either let the client launch it, or connect to the already-running process by URL:
…or, from a local checkout, run it with uv directly:
3. Least-privilege local container¶
Swap docker for podman for a daemonless runtime. Pin the image by digest — the
shipped docker/mcp.compose.yml
requires one (HOME_ASSISTANT_AGENT_MCP_IMAGE) rather than trusting a floating tag.
(a) Launch directly from mcp_config.json (stdio over the container — no ports to manage):
{
"mcpServers": {
"home-assistant-mcp": {
"command": "docker",
"args": [
"run", "-i", "--rm",
"--read-only", "--cap-drop=ALL", "--security-opt=no-new-privileges",
"--pids-limit=256", "--tmpfs", "/tmp:rw,noexec,nosuid,nodev,size=64m",
"-e", "TRANSPORT=stdio",
"-e", "HOME_ASSISTANT_URL=<your-home_assistant_url>",
"-e", "HOME_ASSISTANT_TOKEN=<your-home_assistant_token>",
"registry.example.invalid/home-assistant-agent@sha256:<digest>",
"home-assistant-mcp"
]
}
}
}
The operator projects the selected AgentConfig profile into the process at runtime;
the image remains immutable and contains no environment connection profile.
(b) Run a long-lived streamable-http container, then connect by URL:
4. Remote authenticated HTTPS endpoint¶
When the server is deployed remotely and published through a TLS-terminating reverse
proxy, connect with the "url" key — no local process or image required:
Store the real remote URL, outbound identity reference, and TLS-profile reference in
AgentConfig, not in MCP client JSON or documentation. See Behind a Caddy reverse
proxy and DNS with Technitium below for standing one up.
This page covers running home-assistant-agent as a long-lived server: the
a Caddy reverse proxy, and giving it a DNS name with Technitium. To provision the
Home Assistant instance it connects to, see Backing Platform.
home-assistant-agentships two entry points: an MCP server (console scripthome-assistant-mcp) — a typed, deterministic tool surface a policy routerhome-assistant-agent) that wraps that tool surface in a Pydantic-AI graph agent.
Run the MCP server¶
The transport is selected with --transport (or the TRANSPORT env var):
Health check (HTTP transports):
Configuration (environment)¶
home-assistant-agent is configured entirely from the environment. The required
set:
| Var | Default | Meaning |
|---|---|---|
HOME_ASSISTANT_URL |
http://localhost:8123 |
Home Assistant base URL |
HOME_ASSISTANT_TOKEN |
(unset) | Long-lived access token |
TLS_PROFILE / TLS_PROFILE_REF |
(system trust) | AgentConfig private-CA/mTLS profile; verification remains mandatory |
HOST |
0.0.0.0 |
Bind address (HTTP transports) |
PORT |
8000 |
Bind port (HTTP transports) |
TRANSPORT |
stdio |
stdio, streamable-http, or sse |
Each MCP tool domain is registered only when its flag is enabled (all default to
True): CONFIGTOOL, STATESTOOL, SERVICESTOOL, EVENTSTOOL, HISTORYTOOL,
LOGBOOKTOOL, CALENDARTOOL, PANELSTOOL, VOICETOOL, ENTITIESTOOL,
SYSTEMTOOL. The full set, with the agent and observability settings, is documented
in .env.example.
Copy it to .env and fill in only what the operator use.
Docker Compose¶
The repo ships docker/mcp.compose.yml.
It reads a sibling .env and publishes the HTTP server on :8000:
services:
home-assistant-agent-mcp:
image: example/home-assistant-agent@sha256:<digest>
container_name: home-assistant-agent-mcp
hostname: home-assistant-agent-mcp
restart: always
env_file:
- ../.env
environment:
- PYTHONUNBUFFERED=1
- HOST=0.0.0.0
- PORT=8000
- TRANSPORT=streamable-http
ports:
- "8000:8000"
healthcheck:
test: ["CMD", "python3", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8000/health')"]
interval: 30s
timeout: 10s
retries: 3
cp .env.example .env # then edit HOME_ASSISTANT_* values
docker compose -f docker/mcp.compose.yml up -d
docker compose -f docker/mcp.compose.yml logs -f
Behind a Caddy reverse proxy¶
Expose the HTTP server on a hostname with automatic TLS. Add to the operator's Caddyfile:
# Internal (self-signed) — homelab .example.invalid zone
home-assistant-agent.example.invalid {
tls internal
reverse_proxy home-assistant-agent-mcp:8000
}
# Public — automatic Let's Encrypt
home-assistant-agent.example.com {
reverse_proxy home-assistant-agent-mcp:8000
}
Reload Caddy:
DNS with Technitium¶
Point the hostname at the host running Caddy. Via the Technitium API:
curl -s "http://technitium.example.invalid:5380/api/zones/records/add" \
--data-urlencode "token=$TECHNITIUM_DNS_TOKEN" \
--data-urlencode "domain=home-assistant-agent.example.invalid" \
--data-urlencode "zone=arpa" \
--data-urlencode "type=A" \
--data-urlencode "ipAddress=192.0.2.10" \
--data-urlencode "ttl=3600"
…or add an A record home-assistant-agent.example.invalid → <caddy-host-ip> in the
Technitium web console (http://technitium.example.invalid:5380). The ecosystem
technitium-dns-mcp automates
this as a tool.
Register with an MCP client¶
Add to the operator's client's mcp_config.json:
{
"mcpServers": {
"home-assistant-agent": {
"command": "uv",
"args": ["run", "home-assistant-mcp"],
"env": {
"HOME_ASSISTANT_URL": "http://your-home-assistant:8123",
"HOME_ASSISTANT_TOKEN": "your_long_lived_access_token"
}
}
}
}
For a remote HTTP server, point the client at http://home-assistant-agent.example.invalid/mcp
instead.