docs: warn Tailscale Funnel users that Claude.ai connectors need port 443 (#2080) (#2094)

Claude.ai's connector backend does not reliably reach non-standard HTTPS
ports published via Tailscale Funnel (8443, 10000) - connections fail in
every auth mode with no request from Anthropic's range reaching the
server. Document the fix (the Tailscale add-on's built-in Share Home
Assistant option, which serves on port 443) in the FAQ, the site FAQ,
and the Webhook Proxy dev add-on docs.

Co-authored-by: kingpanther13 <kingpanther13@users.noreply.github.com>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: kingpanther13

docs/FAQ.md

@@ -74,6 +74,8 @@ This is a known Claude.ai behavior that affects all MCP servers, not just ha-mcp
 
 **Check for a port in the URL.** Your connector URL is built on your Home Assistant's own public address, which must **not** contain a port such as `:8123` (or any other port). To check, open just that base address (e.g. `https://ha.example.com`, without the `/api/webhook/...` secret path) in a browser — it should bring up your HA login page. Remote clients cannot reach a URL that carries a port, even though it loads fine in your own browser. Home Assistant can still listen on 8123 internally, as long as a reverse proxy, tunnel, or 443 port-forward serves that hostname — just don't put the port in the URL you paste.
 
+**Tailscale Funnel: use port `443`.** Funnel can also serve on the alternate HTTPS ports it offers (`8443`, `10000`), but Claude.ai's connector backend does not reliably reach non-standard ports: the connection fails identically in every auth mode, and no request from Anthropic's range (`160.79.104.0/21`) ever reaches the server — nothing appears in any log. Use standard port `443` instead, where the same setup connects on the first try. The official Tailscale add-on's built-in **"Share Home Assistant with Serve or Funnel"** option already exposes Home Assistant on `443`, so use that hostname in the connector URL (same webhook path). See [#2080](https://github.com/homeassistant-ai/ha-mcp/issues/2080).
+
 ### "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-dev/CHANGELOG.md

@@ -9,6 +9,12 @@ history from before the fork.
 -->
 
 
+## v2.1.1.dev2 (2026-07-30)
+
+Documentation: warn Tailscale Funnel users that Claude.ai connectors require the
+standard HTTPS port 443 (#2080).
+
+
 ## v2.1.1.dev1 (2026-07-26)
 
 Version line rebased onto the 2.1.0 stable base (no code changes — dev and

homeassistant-addon-webhook-proxy-dev/DOCS.md

@@ -46,6 +46,14 @@ automatically on the next clean start.
 
 > **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.
 
+> **Tailscale Funnel: use port 443.** Claude.ai's backend does not reliably
+> reach a Funnel published on a non-standard HTTPS port (`8443`, `10000`) —
+> the connector fails identically in every auth mode (no auth, `legacy`,
+> `ha_auth`) and no request from Anthropic's range ever reaches your logs. Use the
+> Tailscale addon's built-in **Share Home Assistant with Serve or Funnel**
+> option, which publishes on the standard port 443, and build the connector
+> URL on that hostname (same webhook path).
+
 > **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
@@ -94,6 +102,7 @@ http://192.168.1.100:9583/private_zctpwlX7ZkIAr7oqdfLPxw
 
 - **Nabu Casa subscribers**: Leave `remote_url` blank — auto-detected from cloud storage
 - **Cloudflare/DuckDNS/nginx**: Set `remote_url` to your external URL (e.g. `https://ha.example.com`)
+- **Tailscale Funnel**: Use the Tailscale addon's built-in **Share Home Assistant with Serve or Funnel** option, which publishes on port 443, and set `remote_url` to that hostname — Claude.ai cannot reliably reach a Funnel published on an alternate port such as `8443`
 
 Your external URL must point directly at Home Assistant — opening it in a browser should land on your HA login page — and it must **not** contain a port such as `:8123` (or any other port). If the connect URL carries a port, remote MCP clients such as Claude will fail to reach it even though it loads fine in your own browser.
 

homeassistant-addon-webhook-proxy-dev/config.yaml

@@ -1,6 +1,6 @@
 name: "Nabu Casa - Webhook Proxy for HA MCP (Dev)"
 description: "DEV CHANNEL (unstable) — remote access proxy via Nabu Casa or any reverse proxy. Cannot run alongside the stable Webhook Proxy add-on."
-version: "2.1.1.dev1"
+version: "2.1.1.dev2"
 slug: "ha_mcp_webhook_proxy_dev"
 url: "https://github.com/homeassistant-ai/ha-mcp"
 stage: experimental

homeassistant-addon-webhook-proxy-dev/mcp_proxy_dev/manifest.json

@@ -7,5 +7,5 @@
   "dependencies": ["webhook"],
   "documentation": "https://github.com/homeassistant-ai/ha-mcp",
   "iot_class": "local_push",
-  "version": "2.1.1.dev1"
+  "version": "2.1.1.dev2"
 }

site/src/pages/faq.astro

@@ -468,6 +468,7 @@ source ~/.zshrc
             <li><strong>Reachability from Anthropic's servers:</strong> Claude.ai connects from the cloud, not your network — a URL that works in Claude Code or your browser (both on your LAN) can still be unreachable for Claude.ai web. Open the URL on your <strong>phone with Wi-Fi off</strong>; if it doesn't load, it isn't publicly reachable and Claude.ai can't reach it either.</li>
             <li><strong>Don't forget to click <em>Connect</em> on the connector</strong> — and, with OAuth enabled, click <strong>Allow</strong> on the consent page. Adding the connector alone does not complete the connection.</li>
             <li><strong>URL works in your browser but the LLM can't connect?</strong> Your reverse proxy is filtering the AI client — see <a href="#cloudflare-blocks-llm" class="text-blue-400 hover:underline">Cloudflare: LLM can't connect</a> below (Cloudflare's "Block AI training bots" and geo/country blocking are the usual causes).</li>
+            <li><strong>Tailscale Funnel: use port <code class="bg-slate-800 px-1 rounded">443</code>.</strong> Funnel can also serve on the alternate HTTPS ports it offers (<code class="bg-slate-800 px-1 rounded">8443</code>, <code class="bg-slate-800 px-1 rounded">10000</code>), but Claude.ai's connector backend does not reliably reach non-standard ports — the connection fails identically in every auth mode and no request from Anthropic's range (<code class="bg-slate-800 px-1 rounded">160.79.104.0/21</code>) ever reaches the server. The official Tailscale add-on's <strong>"Share Home Assistant with Serve or Funnel"</strong> option already exposes Home Assistant on <code class="bg-slate-800 px-1 rounded">443</code> — use that hostname in the connector URL (same webhook path). See <a href="https://github.com/homeassistant-ai/ha-mcp/issues/2080" target="_blank" rel="noopener noreferrer" class="text-blue-400 hover:underline">#2080</a>.</li>
           </ol>
         </div>