feat(webhook-proxy): inbound-request debug logging + connector docs (#1633)

* feat(webhook-proxy): inbound-request debug logging + connector docs

- Add `debug_logging` toggle (visible on the main Configuration page); logs
  each inbound request to the HA log before the OAuth gate so the 401
  discovery probe is captured too. Confirms whether a client is reaching the
  server. The integration logger is raised to INFO while on.
- Document the Claude.ai web flow (add connector -> Connect -> Allow) and a
  public-reachability check across the addon DOCS, setup site, and FAQ.
- Bump the addon to 1.2.0 and add a backfilled CHANGELOG.md.

Closes #1627

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* test(webhook-proxy): debug_logging tests; sync manifest version; keep OFF-path hass.data shape

- Bump integration manifest.json to 1.2.0 to match config.yaml (the addon/
  integration version-match guard used by start.py update detection).
- Add the debug_logging key to hass.data only when enabled, keeping the
  OFF-path shape identical to baseline (TestOAuthOffPreservesBehavior).
- Add config-structure + TestDebugLogging tests (off/on hass.data shape,
  inbound-request logging); apply ruff format.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(webhook-proxy): address review (request.remote, symmetric logger guard, +tests)

- Log the inbound source from request.remote (the HA-validated client IP)
  rather than the spoofable X-Forwarded-For header.
- Raise the integration logger to INFO only when the effective level is less
  verbose, and on the OFF path only undo an INFO we ourselves raised — never
  clobber a user's explicit `logger:` level in either direction.
- Add tests: 401-before-gate inbound logging, upstream-response log line, and
  all three logger-level branches (with an autouse logger-level reset).
- Revert an unrelated cosmetic ruff reformat of oauth.py swept in by a broad
  `ruff format`.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* ci(webhook-proxy): type-check the mcp_proxy integration under mypy

CI's mypy step only covered start.py, leaving the mcp_proxy integration
package untyped on every platform (not a Windows quirk — it was never in the
mypy command). Bring it under the same gate as custom_components/ and fix the
gaps that surfaced:

- pr.yml: mypy the whole homeassistant-addon-webhook-proxy/ dir, not just
  start.py.
- config_flow.py: annotate the flow methods and `# type: ignore[call-arg]` the
  `domain=` subclass kwarg, mirroring custom_components/ha_mcp_tools.
- oauth.py / __init__.py: fix two no-any-return warnings.
- pyproject.toml: add yarl to the ignore_missing_imports override (it ships
  with aiohttp, already ignored).
- Restore the repo-wide ruff format on oauth.py.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: kingpanther13 <kingpanther13@users.noreply.github.com>
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: kingpanther13

.github/workflows/pr.yml

@@ -249,7 +249,7 @@ jobs:
     - name: Run mypy
       run: |
         uv run mypy src/ custom_components/ homeassistant-addon/ scripts/
-        uv run mypy homeassistant-addon-webhook-proxy/start.py
+        uv run mypy homeassistant-addon-webhook-proxy/
 
   # Fast unit tests (no Docker, no HA instance needed)
   unit-tests:

docs/FAQ.md

@@ -61,6 +61,8 @@ You can also start a new conversation and ask Claude if it can see your Home Ass
 
 This is a known Claude.ai behavior that affects all MCP servers, not just ha-mcp.
 
+**If it genuinely won't connect** (not just the transient handshake error above): Claude.ai connects from Anthropic's servers, so the MCP URL must be reachable from the public internet — not just your LAN. A URL that works in Claude Code or a local browser can still be unreachable for Claude.ai web. Open the URL on your **phone with Wi-Fi off** (cellular): if it doesn't load there, it isn't publicly reachable (DNS / port-forward / TLS / reverse-proxy) and Claude.ai can't reach it either. Also make sure you clicked **Connect** on the connector (and, with OAuth enabled, **Allow** on the consent page) — adding the connector alone does not complete the connection.
+
 ### "Terminating session: None" in server logs
 
 **This is normal.** ha-mcp runs in stateless HTTP mode, which means each request creates and discards a temporary session. The `Terminating session: None` log message is the MCP SDK reporting this routine cleanup — the connection stays active.

homeassistant-addon-webhook-proxy/CHANGELOG.md

@@ -0,0 +1,49 @@
+# CHANGELOG
+
+<!-- version list -->
+
+
+## v1.2.0 (2026-06-15)
+
+### Added
+
+- Add a "Log inbound requests" debug toggle. When enabled, every request that
+  reaches the webhook proxy is logged to the Home Assistant log (method, masked
+  path, source address, whether an `Authorization` header was present, and the
+  upstream response status) — making it easy to confirm whether an MCP client
+  such as Claude.ai is actually reaching the server.
+
+### Documentation
+
+- Document the Claude.ai web custom-connector flow end to end (add the
+  connector, click **Connect**, then **Allow** on the authorization page) and
+  add a quick public-reachability check for diagnosing "Couldn't reach MCP
+  server".
+
+## v1.1.0 (2026-05-09)
+
+### Added
+
+- Optional OAuth 2.1 authentication mode for the webhook proxy (beta)
+  ([#1184](https://github.com/homeassistant-ai/ha-mcp/pull/1184))
+
+## v1.0.2 (2026-05-03)
+
+### Fixed
+
+- Surface webhook registration failures instead of silently loading
+  ([#1101](https://github.com/homeassistant-ai/ha-mcp/pull/1101))
+
+## v1.0.1 (2026-03-07)
+
+### Fixed
+
+- Correct webhook proxy Dockerfile COPY paths for Supervisor builds
+  ([#725](https://github.com/homeassistant-ai/ha-mcp/pull/725))
+
+## v1.0.0 (2026-03-06)
+
+### Added
+
+- Nabu Casa and other generic remote access via the webhook proxy
+  ([#554](https://github.com/homeassistant-ai/ha-mcp/pull/554))

homeassistant-addon-webhook-proxy/DOCS.md

@@ -23,6 +23,14 @@ This addon enables remote access to your HA MCP Server through any reverse proxy
    ```
 5. **Paste the URL** into your MCP client (Claude Desktop, Claude.ai, Open WebUI, etc.)
 
+### Connecting from Claude.ai (web)
+
+1. In Claude.ai, go to **Settings → Connectors → Add custom connector**, give it a name, paste the remote URL, and click **Add**.
+2. **Click _Connect_ on the new connector.** This step is required — adding the connector does not connect it. With OAuth enabled this opens the consent page; click **Allow** to finish. (With OAuth off there is no consent page and it connects directly.)
+3. Claude.ai may briefly show *"Couldn't reach the MCP server"* — this is often a harmless artifact of the initial handshake. Check whether the connector actually shows as connected before assuming it failed.
+
+> **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.
+
 > **Note:** If something doesn't seem to work after restarting HA, try restarting the addon as well.
 
 ## Configuration
@@ -36,8 +44,9 @@ This addon enables remote access to your HA MCP Server through any reverse proxy
 | `oauth_client_id` | OAuth Client ID (auto-generated if blank) | `""` |
 | `oauth_client_secret` | OAuth Client Secret (auto-generated if blank) | `""` |
 | `regenerate_oauth_creds` | One-shot: wipe stored OAuth creds and generate fresh ones on next start | `false` |
+| `debug_logging` | **Beta.** Log every inbound request to the Home Assistant log to confirm a client is reaching the server | `false` |
 
-> The OAuth options are hidden by default. Toggle **Show unused optional configuration options** at the bottom of the addon's Configuration tab to reveal them.
+> The OAuth options are hidden by default. Toggle **Show unused optional configuration options** at the bottom of the addon's Configuration tab to reveal them. `debug_logging` is shown on the main Configuration page (it is not one of the hidden options).
 
 ### Auto-detection
 
@@ -132,7 +141,7 @@ The generated values are persisted at `/data/oauth_creds.json` inside the addon,
 
 ### End-to-end flow (what happens when Claude.ai connects)
 
-When OAuth is enabled and you paste the webhook URL + Client ID + Client Secret into Claude.ai's connector setup, here's what happens:
+When OAuth is enabled and you paste the webhook URL + Client ID + Client Secret into Claude.ai's connector setup, here's what happens after you click **Connect** on the connector:
 
 1. **Claude.ai's browser session** is redirected to `https://<your-host>/authorize?response_type=code&client_id=...&redirect_uri=...&code_challenge=...&code_challenge_method=S256&state=...&resource=https://<your-host>/api/webhook/<id>`.
 2. The addon serves a **consent page** (Allow / Deny) showing the redirect destination so you can verify it's Claude.ai's callback URL before proceeding.
@@ -168,6 +177,24 @@ What stops an attacker who can reach the consent page from gaining access:
 - If you suspect it has leaked, **rotate it immediately** using one of the three rotation methods above. After rotation, the old Client Secret stops working — any tokens previously issued will fail at refresh, forcing the client to re-do the OAuth flow with the new credentials.
 - If you can't tell whether it leaked but want a clean slate (e.g., after sharing logs for debugging, after a migration), rotating proactively is cheap: flip **Regenerate OAuth Credentials on Next Start**, restart, paste the new credentials into Claude.ai. Takes ~30 seconds.
 
+### Debugging connections (log inbound requests)
+
+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:
+
+```
+MCP Proxy [inbound]: POST /api/webhook/mcp_3e... from 203.0.113.4 (Authorization header: present)
+MCP Proxy [inbound]: -> upstream responded 200 (text/event-stream)
+```
+
+How to read it:
+
+- **You see inbound lines** → the client is reaching the server; the problem is downstream (auth, the client's config, or the MCP server itself).
+- **You see nothing** → the request never arrived. The problem is network reachability — the public URL, DNS, TLS, or your reverse proxy — not this addon. See the reachability check under [Setup](#connecting-from-claudeai-web).
+
+Turn it back off for normal operation (restart the addon after changing it).
+
 ## How it works
 
 1. The addon installs a lightweight `mcp_proxy` custom integration into Home Assistant
@@ -203,6 +230,15 @@ 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
 
+### Claude.ai says "Couldn't reach the MCP server"
+
+Two cases:
+
+1. **It actually connected.** Claude.ai sometimes shows this during the initial handshake even though the connector ends up working. Check whether the connector shows as connected before assuming failure.
+2. **It genuinely can't reach the URL.** Claude.ai connects from Anthropic's servers, so the URL must be reachable from the public internet — not just your LAN. Open the remote URL on your **phone with Wi-Fi off** (cellular): if it doesn't load, the URL isn't publicly reachable (DNS / port-forward / TLS / reverse-proxy) and Claude.ai can't reach it either. To confirm whether requests are arriving at all, enable **Log inbound requests** (see [Debugging connections](#debugging-connections-log-inbound-requests)).
+
+> **Note:** A connection working in Claude Code or a local browser but **not** in Claude.ai web is the classic signature of this — those reach your box over the LAN, while Claude.ai reaches it from the public internet.
+
 ## Disabling / Uninstalling
 
 - **Stopping** the addon is safe — the webhook URL stays the same and resumes working when the addon is restarted

homeassistant-addon-webhook-proxy/config.yaml

@@ -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.1.0"
+version: "1.2.0"
 slug: "ha_mcp_webhook_proxy"
 url: "https://github.com/homeassistant-ai/ha-mcp"
 arch:
@@ -19,6 +19,7 @@ options:
   remote_url: ""
   mcp_server_url: ""
   mcp_port: 9583
+  debug_logging: false
 schema:
   remote_url: str?
   mcp_server_url: str?
@@ -27,3 +28,4 @@ schema:
   oauth_client_id: str?
   oauth_client_secret: password?
   regenerate_oauth_creds: bool?
+  debug_logging: bool?

homeassistant-addon-webhook-proxy/mcp_proxy/__init__.py

@@ -36,6 +36,12 @@
 
 _LOGGER = logging.getLogger(__name__)
 
+# Tracks whether *this process* raised the logger to INFO for the debug toggle,
+# so the off path undoes only our own raise — never a level the user set via
+# Home Assistant's `logger:` config. Module-global (not hass.data) because it
+# must survive a config-entry reload, during which hass.data[DOMAIN] is gone.
+_LOGGER_LEVEL_RAISED = False
+
 DOMAIN = "mcp_proxy"
 CONFIG_FILE = Path("/config/.mcp_proxy_config.json")
 
@@ -87,12 +93,11 @@ async def async_setup(hass: HomeAssistant, config: ConfigType) -> bool:
             "You can safely remove 'mcp_proxy:' from configuration.yaml."
         )
         hass.async_create_task(
-            hass.config_entries.flow.async_init(
-                DOMAIN, context={"source": "import"}
-            )
+            hass.config_entries.flow.async_init(DOMAIN, context={"source": "import"})
         )
     if await hass.async_add_executor_job(_marker_present):
         from .repairs import maybe_create_issue
+
         maybe_create_issue(hass, DOMAIN)
     return True
 
@@ -101,6 +106,7 @@ def _marker_present() -> bool:
     # Imported lazily so async_setup doesn't pull in repairs.py module-load
     # cost on the no-marker happy path.
     from .repairs import marker_present
+
     return marker_present()
 
 
@@ -158,6 +164,31 @@ async def async_setup_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
     _LOGGER.info("MCP Proxy: target = %s", masked_target)
     _LOGGER.info("MCP Proxy: webhook endpoint = /api/webhook/%s", masked_wh)
 
+    # Inbound-request debug logging (addon "Log inbound requests" toggle).
+    # Custom-component loggers default to WARNING, so when the toggle is on we
+    # raise our own logger to INFO so the per-request lines are emitted — but
+    # only when the effective level is less verbose, so we never override an
+    # explicit DEBUG/INFO the user set via Home Assistant's `logger:` config. We
+    # track whether WE raised it and, when the toggle is off, undo only our own
+    # raise — never a level the user set themselves.
+    global _LOGGER_LEVEL_RAISED
+    debug_logging = bool(proxy_config.get("debug_logging", False))
+    if debug_logging and _LOGGER.getEffectiveLevel() > logging.INFO:
+        _LOGGER.setLevel(logging.INFO)
+        _LOGGER_LEVEL_RAISED = True
+    elif not debug_logging and _LOGGER_LEVEL_RAISED:
+        # Undo only the INFO we raised. (If a user had set an explicit level
+        # quieter than INFO — ERROR/CRITICAL — then toggled debug on then off,
+        # this resets to NOTSET rather than their original level; restoring that
+        # would need durable per-level state, not worth it for a debug aid.)
+        _LOGGER.setLevel(logging.NOTSET)
+        _LOGGER_LEVEL_RAISED = False
+    if debug_logging:
+        _LOGGER.info(
+            "MCP Proxy: inbound request debug logging is ON — each request to "
+            "this webhook will be logged here."
+        )
+
     session = aiohttp.ClientSession(
         timeout=aiohttp.ClientTimeout(total=300, sock_connect=10, sock_read=300),
     )
@@ -177,15 +208,18 @@ async def async_setup_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
             masked_wh,
         )
         await session.close()
-        raise ConfigEntryError(
-            f"Failed to register webhook endpoint: {err}"
-        ) from err
+        raise ConfigEntryError(f"Failed to register webhook endpoint: {err}") from err
 
     hass_data: dict = {
         "target_url": target_url,
         "webhook_id": webhook_id,
         "session": session,
     }
+    # Mirror the oauth pattern: only add the key when the feature is on, so the
+    # default/OFF path's hass.data shape stays identical to the baseline
+    # (target_url, webhook_id, session) — guarded by TestOAuthOffPreservesBehavior.
+    if debug_logging:
+        hass_data["debug_logging"] = True
 
     # OAuth is opt-in. When the addon writes an `oauth` section into the
     # config file (only when enable_oauth is on AND both creds are non-empty,
@@ -215,11 +249,10 @@ async def async_setup_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
         if not isinstance(public_base_url, str) or not public_base_url:
             public_base_url = None
         from .oauth import OAuthProvider, load_or_create_secret
+
         try:
             # Filesystem I/O — must run off the event loop.
-            signing_key = await hass.async_add_executor_job(
-                load_or_create_secret
-            )
+            signing_key = await hass.async_add_executor_job(load_or_create_secret)
             oauth_provider = OAuthProvider(
                 hass=hass,
                 client_id=client_id,
@@ -256,6 +289,7 @@ async def async_setup_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
     # in the executor; the issue-registry call is synchronous and safe on
     # the event loop.
     from .repairs import _clear_marker, _delete_issue_only
+
     await hass.async_add_executor_job(_clear_marker)
     _delete_issue_only(hass, DOMAIN)
 
@@ -271,7 +305,8 @@ def _read_config() -> dict | None:
     """
     if not CONFIG_FILE.exists():
         return None
-    return json.loads(CONFIG_FILE.read_text())
+    data: dict | None = json.loads(CONFIG_FILE.read_text())
+    return data
 
 
 async def _handle_webhook(
@@ -281,12 +316,39 @@ async def _handle_webhook(
     data = hass.data[DOMAIN]
     target_url = data["target_url"]
 
+    # Inbound-request debug logging (opt-in). Logged BEFORE the OAuth gate so
+    # the unauthenticated discovery probe (which gets a 401) is captured too —
+    # that probe arriving is the proof a client actually reached the server.
+    debug = data.get("debug_logging")
+    if debug:
+        wh = data["webhook_id"]
+        masked_path = f"/api/webhook/{wh[:6]}..." if len(wh) > 6 else "/api/webhook/***"
+        # request.remote is the client IP validated by HA's trusted-proxy layer
+        # (it resolves X-Forwarded-For when the proxy is trusted). Reading the
+        # raw X-Forwarded-For header here would let an untrusted client spoof
+        # 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,
+        )
+
     # OAuth gate. When OAuth isn't configured, `oauth_provider` is None and
     # this branch is a single attribute lookup with zero behavior change vs
     # the original handler.
     oauth_provider = data.get("oauth")
     if oauth_provider is not None and not oauth_provider.validate_bearer(request):
+        if debug:
+            _LOGGER.info(
+                "MCP Proxy [inbound]: -> 401 Unauthorized (no/invalid OAuth "
+                "bearer; expected for the initial discovery probe)"
+            )
         from .oauth import build_unauthorized_response
+
         return build_unauthorized_response(request, oauth_provider)
 
     body = await request.read()
@@ -295,8 +357,12 @@ async def _handle_webhook(
     forward_headers = {}
     for key, value in request.headers.items():
         if key.lower() in (
-            "host", "content-length", "transfer-encoding", "connection",
-            "cookie", "authorization",
+            "host",
+            "content-length",
+            "transfer-encoding",
+            "connection",
+            "cookie",
+            "authorization",
         ):
             continue
         forward_headers[key] = value
@@ -314,6 +380,13 @@ async def _handle_webhook(
         ) as upstream_resp:
             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",
+                )
+
             # Common headers for both streaming and non-streaming
             resp_headers = {
                 "Cache-Control": "no-cache, no-transform",

homeassistant-addon-webhook-proxy/mcp_proxy/config_flow.py

@@ -1,16 +1,22 @@
 """Config flow for MCP Webhook Proxy."""
 
-from homeassistant.config_entries import ConfigFlow
+from __future__ import annotations
+
+from typing import Any
+
+from homeassistant.config_entries import ConfigFlow, ConfigFlowResult
 
 DOMAIN = "mcp_proxy"
 
 
-class McpProxyConfigFlow(ConfigFlow, domain=DOMAIN):
+class McpProxyConfigFlow(ConfigFlow, domain=DOMAIN):  # type: ignore[call-arg]
     """Handle a config flow for MCP Webhook Proxy."""
 
     VERSION = 1
 
-    async def async_step_user(self, user_input=None):
+    async def async_step_user(
+        self, user_input: dict[str, Any] | None = None
+    ) -> ConfigFlowResult:
         """Handle setup via the UI."""
         await self.async_set_unique_id(DOMAIN)
         self._abort_if_unique_id_configured()
@@ -20,7 +26,9 @@ async def async_step_user(self, user_input=None):
 
         return self.async_show_form(step_id="user")
 
-    async def async_step_import(self, import_data=None):
+    async def async_step_import(
+        self, import_data: dict[str, Any] | None = None
+    ) -> ConfigFlowResult:
         """Handle auto-import from YAML migration or addon API call."""
         await self.async_set_unique_id(DOMAIN)
         self._abort_if_unique_id_configured()