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
- Home Assistant 2025.1+ with the Selora AI integration installed.
- A Selora Connect account with your HA installation linked.
- OpenClaw installed.
1. Get Your MCP URL
| Access | URL |
|---|
| Local | http://homeassistant.local:8123/api/selora_ai/mcp |
| Remote | https://mcp-<id>.selorabox.com/api/selora_ai/mcp |
Your remote MCP URL (including your mcp-<id>) 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-<id>.selorabox.com/api/selora_ai/mcp"}'
Or edit ~/.openclaw/openclaw.json directly:
{
"mcp": {
"servers": {
"home-assistant": {
"url": "https://mcp-<id>.selorabox.com/api/selora_ai/mcp"
}
}
}
}
For local access, use http://homeassistant.local:8123/api/selora_ai/mcp as the URL.
3. Authenticate
- Restart the OpenClaw gateway after editing the config.
- Use any tool from the server (e.g. ask "Get a snapshot of my home"). OpenClaw connects and receives a
401 Unauthorized.
- OpenClaw surfaces an authorization URL. Open it in a browser.
- Approve access on the Selora Connect consent screen.
- The browser redirects back to OpenClaw's callback to complete the exchange.
- 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:
| Tool | Description |
|---|
selora_get_home_snapshot | Entity states grouped by area — call this first |
selora_list_automations | Selora automations with status and risk (filterable) |
selora_get_automation | Full detail: YAML, versions, risk |
selora_validate_automation | Validate and risk-assess YAML without creating |
selora_list_sessions | Recent chat sessions |
selora_list_patterns | Detected behavior patterns |
selora_get_pattern | Full pattern detail with linked suggestions |
selora_list_suggestions | Proactive suggestions with YAML previews |
Mutating tools (🔒 require admin authorization):
| Tool | Description |
|---|
selora_chat 🔒 | Natural-language chat — proposes automations with YAML and risk |
selora_create_automation 🔒 | Create automation from YAML (disabled by default) |
selora_accept_automation 🔒 | Enable a pending automation |
selora_delete_automation 🔒 | Delete permanently |
selora_accept_suggestion 🔒 | Create automation from a suggestion |
selora_dismiss_suggestion 🔒 | Dismiss a suggestion |
selora_trigger_scan 🔒 | Trigger immediate suggestion scan (rate-limited 60s) |
Workflows
Explore your home
selora_get_home_snapshot — understand entities and areas.selora_list_automations / selora_get_automation for existing automations.
Create from YAML
selora_validate_automation — check YAML and surface risk.- Show normalized YAML + risk, ask user confirmation.
selora_create_automation with enabled=false.selora_accept_automation after explicit approval.
Create from natural language
selora_chat — describe what you want; Selora returns YAML + risk.- Summarize risk, ask user confirmation.
selora_create_automation or selora_accept_automation.
Act on suggestions
selora_list_suggestions (optionally selora_trigger_scan first).- Show suggestion details, ask user confirmation.
selora_accept_suggestion or selora_dismiss_suggestion.
Safety Rules
- Never invent IDs — resolve from tool output only.
- Never mutate without explicit user confirmation.
- Always surface
risk_assessment before mutating. High or missing risk requires a second confirmation.
- Create automations disabled by default.
- Do not skip validation for externally provided YAML.
How OAuth Works
- OpenClaw discovers Connect's OAuth server from the MCP endpoint's
.well-known/oauth-authorization-server metadata.
- OpenClaw registers itself dynamically (
POST /oauth/register).
- OpenClaw starts an authorization code flow with PKCE and surfaces an authorization URL.
- You open the URL and approve access on the Selora Connect consent screen.
- OpenClaw exchanges the code for access + refresh tokens.
- 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
| Symptom | Fix |
|---|
401 Unauthorized (auth URL shown) | Open the authorization URL, approve access on Selora Connect, and the flow completes automatically. If refresh fails later, OpenClaw triggers a new flow. |
401 Unauthorized loop (no auth URL shown) | OpenClaw's native OAuth flow is not surfacing the authorization URL — check gateway logs for 401, auth URL emission, and MCP startup failures. See Debugging with mcp-remote below. |
| Connection refused | Verify HA is running and URL is correct |
| Timeout | Check firewall; for remote, ensure SeloraBox tunnel is active |
| Tools not listed | Ensure Selora AI integration is installed and enabled |
| Admin tools rejected | Selora Connect role must be owner or member (not viewer) |
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-<id>.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.
