Model Context Protocol (MCP)

In this homelab, several MCP servers are deployed to provide different levels of control:

• Home Assistant MCP: Controls smart home devices and entities.
• Homelab SSH MCP: Manages and monitors system services and logs.

---

Home Assistant MCP

Ports

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

External Access

Access Method	URL
Local network	http://<homelab.ip>: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>"
      }
    }
  }
}

Connection in OpenClaw

The Telegram bot agent connects using streamable-http transport via the local network (not through Cloudflare) for lower latency:

{
  "mcp": {
    "servers": {
      "home-assistant": {
        "url": "http://127.0.0.1:8123/api/mcp",
        "transport": "streamable-http",
        "headers": {
          "Authorization": "Bearer <HA_TOKEN>"
        }
      }
    }
  }
}

Connection in PicoClaw

Similar to OpenClaw, PicoClaw uses the local streamable-http endpoint:

{
  "tools": {
    "mcp": {
      "servers": {
        "home-assistant": {
          "url": "http://127.0.0.1:8123/api/mcp",
          "transport": "streamable-http",
          "headers": {
            "Authorization": "Bearer <HA_TOKEN>"
          }
        }
      }
    }
  }
}

Connection in LiteLLM

LiteLLM acts as a high-performance proxy and MCP registry. It connects to Home Assistant via the local network:

mcp_servers:
  home_assistant:
    url: "http://127.0.0.1:8123/api/mcp"
    auth_type: "bearer_token"
    auth_value: "$HA_TOKEN"

litellm_settings:
  enable_mcp_registry: true

Proxy API Usage (CURL)

When accessing MCP tools via the LiteLLM proxy API, you must use a specialized tool definition format:

"tools": [
  {
    "type": "mcp",
    "server_url": "litellm_proxy/mcp/home_assistant",
    "server_label": "home_assistant",
    "require_approval": "never"
  }
]

For more details, see the LiteLLM Documentation.

Security

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