homeassistant-ai
diff --git a/‎homeassistant-addon-webhook-proxy/CHANGELOG.md‎
Lines changed: 32 additions & 0 deletions b/‎homeassistant-addon-webhook-proxy/CHANGELOG.md‎
Lines changed: 32 additions & 0 deletions
diff --git a/‎homeassistant-addon-webhook-proxy/DOCS.md‎
Lines changed: 29 additions & 2 deletions b/‎homeassistant-addon-webhook-proxy/DOCS.md‎
Lines changed: 29 additions & 2 deletions
diff --git a/‎homeassistant-addon-webhook-proxy/config.yaml‎
Lines changed: 1 addition & 1 deletion b/‎homeassistant-addon-webhook-proxy/config.yaml‎
Lines changed: 1 addition & 1 deletion
diff --git a/‎homeassistant-addon-webhook-proxy/mcp_proxy/__init__.py‎
Lines changed: 64 additions & 12 deletions b/‎homeassistant-addon-webhook-proxy/mcp_proxy/__init__.py‎
Lines changed: 64 additions & 12 deletions
diff --git a/‎homeassistant-addon-webhook-proxy/mcp_proxy/manifest.json‎
Lines changed: 1 addition & 1 deletion b/‎homeassistant-addon-webhook-proxy/mcp_proxy/manifest.json‎
Lines changed: 1 addition & 1 deletion
diff --git a/‎homeassistant-addon-webhook-proxy/mcp_proxy/oauth.py‎
Lines changed: 62 additions & 18 deletions b/‎homeassistant-addon-webhook-proxy/mcp_proxy/oauth.py‎
Lines changed: 62 additions & 18 deletions
@@ -3,6 +3,38 @@
 <!-- version list -->
 
 
+## v1.2.1 (2026-06-28)
+
+### Added
+
+- Mirror inbound-request debug lines into the addon's own log. When "Log
+  inbound requests" is on, the lines that were previously only visible in the
+  Home Assistant log (Settings → System → Logs) now also appear on the addon's
+  Log tab, so you can confirm a client is reaching the server without leaving
+  the addon page.
+
+### Fixed
+
+- Log a shutdown reason and run cleanup on a Supervisor stop. The addon now
+  handles `SIGTERM`/`SIGINT`, so stopping it unregisters the webhook (as the
+  docs describe) and records why it exited, instead of being killed mid-loop
+  with no log line and the webhook left registered.
+
+- Append a "fully restart Home Assistant" hint to the OAuth stale-registration
+  errors (`invalid_client` and the browser "Invalid client id" page). The OAuth
+  HTTP views only refresh on a full HA restart, so a regenerate / OAuth toggle /
+  reinstall can otherwise leave a stale error with no obvious fix. (Client-side
+  protocol errors and the upstream 502/500 paths don't get the hint — a restart
+  isn't the fix there.)
+
+### Documentation
+
+- Warn that the Claude.ai connector must be deleted and re-created when OAuth
+  is toggled on/off or the webhook URL changes — Claude.ai caches the
+  authentication mode and URL per connector, so reusing the old one fails (for
+  example `invalid client id` on the consent page).
+
+
 ## v1.2.0 (2026-06-15)
 
 ### Added
 
@@ -31,6 +31,16 @@ This addon enables remote access to your HA MCP Server through any reverse proxy
 
 > **Reachability check:** Claude.ai connects from Anthropic's servers, not from your computer — so the URL must be reachable from the public internet, not just your LAN. If a connection won't establish, open the remote URL on your **phone with Wi-Fi turned off** (cellular only). If it doesn't load there, the URL isn't publicly reachable (a DNS, port-forward, TLS, or reverse-proxy problem) and Claude.ai can't reach it either — fix that first.
 
+> **Recreate the connector when OAuth or the URL changes.** Claude.ai binds an
+> authentication mode to a connector when you add it, and caches it. If you
+> later **turn OAuth on or off**, or the **webhook URL changes** (you rotated
+> it, or reinstalled the addon — which generates a new URL), the existing
+> connector keeps using the old mode/URL and tool calls fail (often
+> `invalid client id` on the consent page, or a silently dead endpoint).
+> **Delete the connector in Claude.ai and add a fresh one** with the current
+> URL (and current OAuth Client ID/Secret, if OAuth is on). This is required
+> even when going from OAuth on → off.
+
 > **Note:** If something doesn't seem to work after restarting HA, try restarting the addon as well.
 
 ## Configuration
@@ -181,7 +191,7 @@ What stops an attacker who can reach the consent page from gaining access:
 
 If a client (e.g. Claude.ai) can't connect and you can't tell whether its requests are even reaching Home Assistant, turn on **Log inbound requests** (the `debug_logging` option on the main Configuration page) and **restart the addon**.
 
-When it's on, every request that hits the webhook is logged to the **Home Assistant log** — *not* this addon's log, because requests reach Home Assistant directly rather than passing through the addon process. View them at **Settings → System → Logs** (or filter for `mcp_proxy`). Each line shows the method, a masked webhook path, the source address, whether an `Authorization` header was present, and the upstream response status:
+When it's on, every request that hits the webhook is logged to the **Home Assistant log** (requests reach Home Assistant directly rather than passing through the addon process). View them at **Settings → System → Logs** (or filter for `mcp_proxy`). The same lines are also **mirrored into this addon's own log**, so you can watch them on the addon's Log tab without leaving the addon page. Each line shows the method, a masked webhook path, the source address, whether an `Authorization` header was present, and the upstream response status:
 
 ```
 MCP Proxy [inbound]: POST /api/webhook/mcp_3e... from 203.0.113.4 (Authorization header: present)
@@ -230,6 +240,21 @@ If the `mcp_proxy` integration doesn't appear in Settings > Devices & Services:
 1. Restart Home Assistant (Settings > System > Restart)
 2. The addon will start automatically and retry setup
 
+### Persistent errors, especially OAuth "Invalid client id"
+
+If the proxy keeps returning the same error — most notably **"Invalid client id"**
+on the OAuth consent page even though you pasted the correct Client ID — **fully
+restart Home Assistant** (Settings → System → Restart).
+
+The OAuth provider's HTTP views are bound into Home Assistant's HTTP layer when the
+integration first loads, and Home Assistant can't re-register or drop them on a
+config reload. So changes that come from **toggling OAuth on/off, regenerating
+credentials, or reinstalling the add-on** don't take effect until a full HA
+restart — *reloading the integration or restarting the add-on is not enough.* (The
+webhook endpoint itself is re-registered on every reload, so it's specifically the
+OAuth views that need the restart.) After the restart, re-add the Claude.ai
+connector with the current URL (and current Client ID/Secret, if OAuth is on).
+
 ### Claude.ai says "Couldn't reach the MCP server"
 
 Two cases:
@@ -242,10 +267,12 @@ Two cases:
 ## Disabling / Uninstalling
 
 - **Stopping** the addon is safe — the webhook URL stays the same and resumes working when the addon is restarted
+- **Reinstalling** the addon always changes the webhook URL. Uninstalling wipes the addon's `/data` (where `webhook_id.txt` is stored), so the next start generates a fresh webhook id and overwrites `/config/.mcp_proxy_config.json` with it. Update your MCP client (and re-add the Claude.ai connector) with the new URL afterwards.
 - **Uninstalling** the addon does not automatically remove the custom integration files. To fully clean up after uninstalling:
   1. Delete `/config/custom_components/mcp_proxy/`
   2. Delete `/config/.mcp_proxy_config.json`
-  3. Restart Home Assistant
+  3. Delete `/config/.mcp_proxy_inbound.log` (only present if you used **Log inbound requests**; normally removed when the addon stops)
+  4. Restart Home Assistant
 
 ## Support
 
 
@@ -1,6 +1,6 @@
 name: "Nabu Casa / Webhook Proxy for HA MCP"
 description: "Remote access proxy via Nabu Casa or any reverse proxy (Cloudflare, DuckDNS, nginx)"
-version: "1.2.0"
+version: "1.2.1"
 slug: "ha_mcp_webhook_proxy"
 url: "https://github.com/homeassistant-ai/ha-mcp"
 arch:
 
@@ -20,6 +20,7 @@
 import json
 import logging
 import re
+import threading
 from pathlib import Path
 from urllib.parse import urlparse
 
@@ -46,6 +47,19 @@
 DOMAIN = "mcp_proxy"
 CONFIG_FILE = Path("/config/.mcp_proxy_config.json")
 
+# Inbound-request mirror file. When "Log inbound requests" is on we append each
+# inbound debug line here in addition to logging it to Home Assistant, so the
+# Webhook Proxy addon (a separate process) can tail it and surface the same
+# lines in the addon log. Path kept in sync with start.py:INBOUND_LOG_FILE.
+INBOUND_LOG_FILE = Path("/config/.mcp_proxy_inbound.log")
+# Cap the mirror file so it can't grow without bound; trim to the last half
+# when exceeded. 256 KiB keeps plenty of recent history at ~100 bytes/line.
+_INBOUND_LOG_CAP = 256 * 1024
+# Serializes writes to INBOUND_LOG_FILE: HA dispatches _append_inbound_log to a
+# multi-worker executor pool, so concurrent inbound requests could interleave
+# the append + the cap's read-modify-write trim without this lock.
+_LOG_WRITE_LOCK = threading.Lock()
+
 # ha-mcp generates a 22-char base64url token after `/private_`. We accept >=16
 # as a sanity floor — a truncated/corrupted ha-mcp config yields a shorter
 # token, which is the failure mode this length check exists to catch.
@@ -320,6 +334,45 @@ def _read_config() -> dict | None:
     return data
 
 
+def _append_inbound_log(line: str) -> None:
+    """Append one inbound-debug line to the mirror file the addon tails.
+
+    Capped: when the file grows past ``_INBOUND_LOG_CAP`` it is trimmed to its
+    last half (dropping the now-partial first line) so it can't grow without
+    bound. Best-effort — swallows its own ``OSError`` (e.g. a read-only
+    ``/config``) so a mirror failure never surfaces as an unretrieved executor
+    exception. Blocking filesystem I/O — call via ``hass.async_add_executor_job``.
+    """
+    try:
+        with _LOG_WRITE_LOCK:
+            with INBOUND_LOG_FILE.open("a", encoding="utf-8") as fh:
+                fh.write(line + "\n")
+            if INBOUND_LOG_FILE.stat().st_size > _INBOUND_LOG_CAP:
+                data = INBOUND_LOG_FILE.read_bytes()[-(_INBOUND_LOG_CAP // 2) :]
+                nl = data.find(b"\n")
+                if nl != -1:
+                    data = data[nl + 1 :]
+                INBOUND_LOG_FILE.write_bytes(data)
+    except OSError as e:
+        _LOGGER.debug("MCP Proxy: inbound mirror write failed: %s", e)
+
+
+async def _debug_log(hass: HomeAssistant, message: str) -> None:
+    """Log an inbound-request debug line to Home Assistant AND mirror it to the
+    addon log file (``INBOUND_LOG_FILE``) so it surfaces in the Webhook Proxy
+    addon log too, not only in Settings -> System -> Logs.
+
+    The mirror write is dispatched to the executor fire-and-forget: it runs off
+    the event loop and we deliberately don't await it, so an opt-in debug log
+    never adds latency to (or fails) the proxied request. ``_append_inbound_log``
+    swallows its own ``OSError`` (the only realistic failure here, since the
+    message is controlled ASCII), so the unawaited future does not carry an
+    exception in practice.
+    """
+    _LOGGER.info("%s", message)
+    hass.async_add_executor_job(_append_inbound_log, message)
+
+
 async def _handle_webhook(
     hass: HomeAssistant, webhook_id: str, request: web.Request
 ) -> web.StreamResponse:
@@ -340,12 +393,10 @@ async def _handle_webhook(
         # the logged source.
         source = request.remote or "unknown"
         has_auth = "present" if request.headers.get("Authorization") else "absent"
-        _LOGGER.info(
-            "MCP Proxy [inbound]: %s %s from %s (Authorization header: %s)",
-            request.method,
-            masked_path,
-            source,
-            has_auth,
+        await _debug_log(
+            hass,
+            f"MCP Proxy [inbound]: {request.method} {masked_path} from {source} "
+            f"(Authorization header: {has_auth})",
         )
 
     # OAuth gate. When OAuth isn't configured, `oauth_provider` is None and
@@ -354,9 +405,10 @@ async def _handle_webhook(
     oauth_provider = data.get("oauth")
     if oauth_provider is not None and not oauth_provider.validate_bearer(request):
         if debug:
-            _LOGGER.info(
+            await _debug_log(
+                hass,
                 "MCP Proxy [inbound]: -> 401 Unauthorized (no/invalid OAuth "
-                "bearer; expected for the initial discovery probe)"
+                "bearer; expected for the initial discovery probe)",
             )
         from .oauth import build_unauthorized_response
 
@@ -392,10 +444,10 @@ async def _handle_webhook(
             content_type = upstream_resp.headers.get("Content-Type", "")
 
             if debug:
-                _LOGGER.info(
-                    "MCP Proxy [inbound]: -> upstream responded %s (%s)",
-                    upstream_resp.status,
-                    content_type or "no content-type",
+                await _debug_log(
+                    hass,
+                    f"MCP Proxy [inbound]: -> upstream responded "
+                    f"{upstream_resp.status} ({content_type or 'no content-type'})",
                 )
 
             # Common headers for both streaming and non-streaming
 
@@ -7,5 +7,5 @@
   "dependencies": ["webhook"],
   "documentation": "https://github.com/homeassistant-ai/ha-mcp",
   "iot_class": "local_push",
-  "version": "1.2.0"
+  "version": "1.2.1"
 }
@@ -79,6 +79,53 @@
 # misconfiguration if a future caller forgets the up-front check.
 MIN_CLIENT_ID_LEN = 16
 
+# Appended ONLY to the stale-OAuth-registration errors (invalid_client /
+# invalid client_id) via the _text_error/_json_error restart_hint flag. The OAuth
+# provider's HTTP views are bound at register_views() time and HA can't
+# re-register / drop them mid-session, so a client-id regenerate / OAuth toggle /
+# reinstall only takes effect on a full HA restart — the case this targets
+# (issue #1694). Deliberately NOT added to client-side protocol errors
+# (invalid_grant / invalid_request / unsupported_grant_type) or the webhook
+# 502/500 paths, where a restart is not the fix. (The webhook itself is
+# re-registered on reload; only the OAuth views need the restart.)
+RESTART_HINT = (
+    "If this persists, fully restart Home Assistant "
+    "(Settings -> System -> Restart) — not just the add-on or the integration."
+)
+
+
+def _text_error(
+    status: int, message: str, *, restart_hint: bool = False
+) -> web.Response:
+    """Plain-text error response.
+
+    ``restart_hint`` appends ``RESTART_HINT`` — set it only for the
+    stale-OAuth-registration cases (``invalid client_id``) a full HA restart
+    actually unsticks, not for client-side request mistakes.
+    """
+    text = f"{message}. {RESTART_HINT}" if restart_hint else message
+    return web.Response(status=status, text=text)
+
+
+def _json_error(
+    error: str,
+    status: int,
+    headers: dict[str, str] | None = None,
+    *,
+    restart_hint: bool = False,
+) -> web.Response:
+    """OAuth JSON error response.
+
+    ``restart_hint`` carries ``RESTART_HINT`` in ``error_description`` — set it
+    only for the stale-registration case (``invalid_client``), not for
+    client-side protocol errors (``invalid_grant`` / ``invalid_request`` /
+    ``unsupported_grant_type``) where a restart is not the fix.
+    """
+    body = {"error": error}
+    if restart_hint:
+        body["error_description"] = RESTART_HINT
+    return web.json_response(body, status=status, headers=headers)
+
 
 class _PendingCode(TypedDict):
     """Shape of an entry in OAuthProvider._codes. TypedDict so a typo on
@@ -546,7 +593,7 @@ async def post(self, request: web.Request) -> web.Response:
         if action == "deny":
             return self._redirect_with(redirect_uri, error="access_denied", state=state)
         if action != "approve":
-            return web.Response(status=400, text="invalid action")
+            return _text_error(400, "invalid action")
 
         code = self._provider.issue_code(redirect_uri, code_challenge)
         if code is None:
@@ -571,21 +618,17 @@ def _validate_authorize_params(
         identical validation — the POST path explicitly re-validates the
         hidden form fields rather than trusting them."""
         if response_type != "code":
-            return web.Response(status=400, text="unsupported_response_type")
+            return _text_error(400, "unsupported_response_type")
         if code_challenge_method != "S256":
-            return web.Response(
-                status=400, text="invalid code_challenge_method (S256 required)"
-            )
+            return _text_error(400, "invalid code_challenge_method (S256 required)")
         if not _PKCE_CHALLENGE_RE.match(code_challenge):
-            return web.Response(
-                status=400, text="invalid code_challenge (must be 43-char base64url)"
+            return _text_error(
+                400, "invalid code_challenge (must be 43-char base64url)"
             )
         if client_id != self._provider.client_id:
-            return web.Response(status=400, text="invalid client_id")
+            return _text_error(400, "invalid client_id", restart_hint=True)
         if not _is_valid_redirect_uri(redirect_uri):
-            return web.Response(
-                status=400, text="redirect_uri must be an https:// URL with a host"
-            )
+            return _text_error(400, "redirect_uri must be an https:// URL with a host")
         return None
 
 
@@ -623,27 +666,28 @@ async def post(self, request: web.Request) -> web.Response:
         form = dict(await request.post())
         client_id, client_secret = self._extract_client_creds(request, form)
         if not self._provider.authenticate_client(client_id, client_secret):
-            return web.json_response(
-                {"error": "invalid_client"},
-                status=401,
+            return _json_error(
+                "invalid_client",
+                401,
                 headers={"WWW-Authenticate": 'Basic realm="MCP Proxy OAuth"'},
+                restart_hint=True,
             )
 
         grant_type = form.get("grant_type", "")
         if grant_type == "authorization_code":
             return await self._handle_authorization_code(form)
         if grant_type == "refresh_token":
             return await self._handle_refresh(form)
-        return web.json_response({"error": "unsupported_grant_type"}, status=400)
+        return _json_error("unsupported_grant_type", 400)
 
     async def _handle_authorization_code(self, form: dict) -> web.Response:
         code = str(form.get("code", ""))
         redirect_uri = str(form.get("redirect_uri", ""))
         code_verifier = str(form.get("code_verifier", ""))
         if not (code and redirect_uri and code_verifier):
-            return web.json_response({"error": "invalid_request"}, status=400)
+            return _json_error("invalid_request", 400)
         if not self._provider.consume_code(code, redirect_uri, code_verifier):
-            return web.json_response({"error": "invalid_grant"}, status=400)
+            return _json_error("invalid_grant", 400)
         return web.json_response(
             {
                 "access_token": self._provider.issue_access_token(),
@@ -656,7 +700,7 @@ async def _handle_authorization_code(self, form: dict) -> web.Response:
     async def _handle_refresh(self, form: dict) -> web.Response:
         refresh = str(form.get("refresh_token", ""))
         if not refresh or not self._provider.validate_refresh_token(refresh):
-            return web.json_response({"error": "invalid_grant"}, status=400)
+            return _json_error("invalid_grant", 400)
         return web.json_response(
             {
                 "access_token": self._provider.issue_access_token(),
Original file line number	Diff line number	Diff line change
`@@ -7,5 +7,5 @@`
`7`	`7`	`"dependencies": ["webhook"],`
`8`	`8`	`"documentation": "https://github.com/homeassistant-ai/ha-mcp",`
`9`	`9`	`"iot_class": "local_push",`
`10`		`- "version": "1.2.0"`
	`10`	`+ "version": "1.2.1"`
`11`	`11`	`}`