Model Context Protocol (MCP)

Overview

The Model Context Protocol (MCP) integration enables Home Assistant to act as a server that exposes its devices, scripts, and state information as “tools” for AI agents. This allows Large Language Models (LLMs) to perform actions like turning on lights, checking sensors, or managing lists directly through a standardized interface.

In this homelab, it serves as the primary communication bridge between the local infrastructure and external AI assistants (like Antigravity or custom bots).

Ports

Port	Protocol	Purpose
8123	TCP	Handled via Home Assistant’s main web/API port.

External Access

Access Method	URL
Local network	http://192.168.1.100:8123/api/mcp
Cloudflare Tunnel	https://home-assistant-home.javiersc.com/api/mcp

Secrets

Access is secured via Long-Lived Access Tokens (LLAT). These tokens are generated in the Home Assistant UI and stored in 1Password.

Secret	1Password Item	Field
MCP Client Token	op://Homelab/Home Assistant - OpenClaw Token/credential	Authentication for AI agents.

Backup

This service’s configuration is stored as part of the Home Assistant database and integration registry.

/var/lib/hass

Data is backed up daily to Backblaze B2 as part of the global Home Assistant backup routine.

Configuration

The integration is enabled in the NixOS configuration using the mcp and mcp_server components.

services.home-assistant = {
  package = pkgs-unstable.home-assistant;
  extraComponents = [
    "mcp"
    "mcp_server"
  ];
};

Connection in Antigravity

The IDE agent is connected using the native SSE (Server-Sent Events) configuration in the global mcp_config.json:

{
  "mcpServers": {
    "homeassistant": {
      "url": "https://home-assistant-home.javiersc.com/api/mcp",
      "headers": {
        "Authorization": "Bearer <TOKEN>"
      }
    }
  }
}

Troubleshooting

Config flow could not be loaded: “Invalid handler specified”

Symptom: Error message in Home Assistant UI when trying to add the MCP integration.

Cause: Home Assistant version is too old or required Python dependencies (mcp_server) are missing in the NixOS environment.

Solution: Ensure you are using pkgs-unstable for Home Assistant and that mcp_server is included in extraComponents.

journalctl -fu home-assistant