Skip to content

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:

{
  "mcpServers": {
    "home-assistant-mcp": { "url": "http://localhost:8000/mcp" }
  }
}

…or, from a local checkout, run it with uv directly:

uv run home-assistant-mcp --transport streamable-http --port 8000

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:

docker compose -f docker/mcp.compose.yml up -d   # from a clone of this repo
{
  "mcpServers": {
    "home-assistant-mcp": { "url": "http://localhost:8000/mcp" }
  }
}

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:

{
  "mcpServers": {
    "home-assistant": {"url": "https://service.example.invalid/mcp"}
  }
}

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-agent ships two entry points: an MCP server (console script home-assistant-mcp) — a typed, deterministic tool surface a policy router home-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):

home-assistant-mcp
For IDE / desktop MCP clients that launch the server as a subprocess.

home-assistant-mcp --transport streamable-http --host 0.0.0.0 --port 8000
A network server with a /health endpoint and /mcp route.

home-assistant-mcp --transport sse --host 0.0.0.0 --port 8000

Health check (HTTP transports):

curl -s http://localhost:8000/health        # {"status":"OK"}

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:

docker compose -f services/caddy/compose.yml exec caddy caddy reload --config /etc/caddy/Caddyfile

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.