Home Assistant MCP Setup

Connect your Home Assistant to OpenClaw. Authentication is handled via OAuth 2.0 through Selora Connect — no manual tokens needed.

Prerequisites

1. Home Assistant 2025.1+ with the Selora AI integration installed.
2. A Selora Connect account with your HA installation linked.
3. OpenClaw installed.

1. Get Your MCP URL

Your remote MCP URL (including your mcp-\x3Cid>) is shown in Selora Connect once MCP remote access is enabled. Enable it to provision a SeloraBox tunnel URL.

Use your HA IP (e.g. 192.168.x.x) instead of homeassistant.local if mDNS is slow.

2. Add the MCP Server

Add the server via the CLI:

openclaw mcp set home-assistant '{"url":"https://mcp-\x3Cid>.selorabox.com/api/selora_ai/mcp"}'

Or edit ~/.openclaw/openclaw.json directly:

{
  "mcp": {
    "servers": {
      "home-assistant": {
        "url": "https://mcp-\x3Cid>.selorabox.com/api/selora_ai/mcp"
      }
    }
  }
}

For local access, use http://homeassistant.local:8123/api/selora_ai/mcp as the URL.

3. Authenticate

1. Restart the OpenClaw gateway after editing the config.
2. Use any tool from the server (e.g. ask "Get a snapshot of my home"). OpenClaw connects and receives a 401 Unauthorized.
3. OpenClaw surfaces an authorization URL. Open it in a browser.
4. Approve access on the Selora Connect consent screen.
5. The browser redirects back to OpenClaw's callback to complete the exchange.
6. Tokens are cached and refresh silently from then on.

The callback must reach OpenClaw's listener. If the browser and OpenClaw are on the same machine, the redirect completes automatically. If they are on different machines, see Cross-device callback mismatch below.

4. Verify

Ask your agent: "Get a snapshot of my home". You should see selora_get_home_snapshot return your entities grouped by area.

Available Tools

Read tools:

Mutating tools (🔒 require admin authorization):

Workflows

Explore your home

1. selora_get_home_snapshot — understand entities and areas.
2. selora_list_automations / selora_get_automation for existing automations.

Create from YAML

1. selora_validate_automation — check YAML and surface risk.
2. Show normalized YAML + risk, ask user confirmation.
3. selora_create_automation with enabled=false.
4. selora_accept_automation after explicit approval.

Create from natural language

1. selora_chat — describe what you want; Selora returns YAML + risk.
2. Summarize risk, ask user confirmation.
3. selora_create_automation or selora_accept_automation.

Act on suggestions

1. selora_list_suggestions (optionally selora_trigger_scan first).
2. Show suggestion details, ask user confirmation.
3. selora_accept_suggestion or selora_dismiss_suggestion.

Safety Rules

1. Never invent IDs — resolve from tool output only.
2. Never mutate without explicit user confirmation.
3. Always surface risk_assessment before mutating. High or missing risk requires a second confirmation.
4. Create automations disabled by default.
5. Do not skip validation for externally provided YAML.

How OAuth Works

1. OpenClaw discovers Connect's OAuth server from the MCP endpoint's .well-known/oauth-authorization-server metadata.
2. OpenClaw registers itself dynamically (POST /oauth/register).
3. OpenClaw starts an authorization code flow with PKCE and surfaces an authorization URL.
4. You open the URL and approve access on the Selora Connect consent screen.
5. OpenClaw exchanges the code for access + refresh tokens.
6. Tokens refresh automatically — no re-auth needed until you revoke access.

On 401 Unauthorized, OpenClaw reads the WWW-Authenticate header, attempts a token refresh, and falls back to a full OAuth flow if refresh fails. No manual re-configuration is needed.

Troubleshooting

Cross-device callback mismatch

The OAuth redirect targets localhost on the machine running OpenClaw. If your browser is on a different machine (e.g. OpenClaw on a server, browser on a laptop), the callback cannot reach OpenClaw's listener and the flow fails silently.

As a fallback, ask the user to copy the full callback URL (including the code and state parameters) from their browser's address bar after approving, and paste it back so the agent can complete the token exchange.

Debugging with mcp-remote

If OpenClaw keeps returning 401 without surfacing an authorization URL, use mcp-remote (requires Node.js 18+) to isolate the problem. It is not part of the normal setup — only a debugging tool.

npx -y mcp-remote https://mcp-\x3Cid>.selorabox.com/api/selora_ai/mcp

This helps verify the endpoint supports OAuth correctly and that the token exchange works end-to-end. If mcp-remote completes the flow successfully, the endpoint is working — the issue is in OpenClaw's OAuth runtime, not your HA setup.