docs: explain reverse-proxy geo-blocking on the browser landing page (#1687)

* docs: explain reverse-proxy geo-blocking on the browser landing page

The landing page served on GET to the MCP URL is the splash users see when
they open their connection URL in a browser. The most common "I see the
welcome page but my AI client can't connect" cause is a reverse-proxy/CDN
geo-blocking rule that drops US IP addresses, where most AI/LLM services
connect from (e.g. Anthropic's 160.79.104.0/21).

Add a section telling users that seeing this page means the URL is set up
correctly, that the block is on the proxy/CDN side rather than HA-MCP, and
pointing them at geo/country rules and their proxy access logs.

Closes #1669.

* docs: anchor the Anthropic IP range to its source-of-truth doc

Add an inline code comment next to the 160.79.104.0/21 literal pointing at
Anthropic's published IP-addresses doc, so a future maintainer knows where
to re-verify the range if it ever changes.

* docs: broaden landing-page connection guidance

Restructure the reverse-proxy section into a list of common causes and add
the ones drawn from issue #1669: name Zoraxy alongside the other proxy
examples (the OP's reverse proxy), restore the WAF/bot-blocking/rate-limiting
check (from the OP's own diagnostic checklist), and note that AI-client
network blips and the client refusing certain domains/proxies can also
prevent a connection.

---------

Co-authored-by: kingpanther13 <kingpanther13@users.noreply.github.com>

Author: kingpanther13

src/ha_mcp/__main__.py

@@ -993,6 +993,31 @@ def register_browser_landing(
         "connector or MCP settings of your AI/LLM client. No username or password required.\n"
         "Setup instructions: https://homeassistant-ai.github.io/ha-mcp/\n"
         "\n"
+        "--- Seeing this page? Your URL is set up correctly ---\n"
+        "\n"
+        "If this page loads in your browser, the MCP server is reachable and the\n"
+        "URL is correct. If your AI client still cannot connect, the problem is\n"
+        "not on HA-MCP's side. Common causes:\n"
+        "\n"
+        "- Geo / country blocking in your reverse proxy / CDN (Cloudflare, NGINX,\n"
+        "  Traefik, Zoraxy, etc.). Most AI/LLM services connect from US-based\n"
+        "  cloud infrastructure, so if you block US IP addresses (or only allow\n"
+        "  your own country), that is why your client cannot connect. Allow your\n"
+        "  provider's IP ranges (or your client's egress IPs). For example,\n"
+        # Anthropic's documented outbound range; re-verify at
+        # https://platform.claude.com/docs/en/api/ip-addresses if it ever changes.
+        "  Claude.ai connects from Anthropic's network, 160.79.104.0/21.\n"
+        "- WAF, bot-blocking, or rate-limiting rules on the proxy that drop or\n"
+        "  challenge the request.\n"
+        "- The AI client's network can sometimes be spotty -- you may just need\n"
+        "  to try connecting again.\n"
+        "- The AI client itself refusing certain domains or proxy providers on\n"
+        "  its end. This is rare and outside your control; try a different\n"
+        "  hostname or proxy if you suspect it.\n"
+        "\n"
+        "Your proxy's access logs will show the blocked attempt -- look for the\n"
+        "request from your AI provider's IP (e.g. an Anthropic 160.79.x.x address).\n"
+        "\n"
         "--- Cloudflare Users ---\n"
         "\n"
         'If your LLM cannot connect, Cloudflare\'s "Block AI training bots"\n'

tests/src/unit/test_browser_landing.py

@@ -46,6 +46,9 @@ async def test_get_returns_405_with_helpful_message(mcp_app):
     assert "Block AI training bots" in resp.text
     assert '"do not block (allow crawlers)"' in resp.text
     assert "dash.cloudflare.com" in resp.text
+    # Reverse-proxy / geo-blocking guidance (issue #1669)
+    assert "Your URL is set up correctly" in resp.text
+    assert "160.79.104.0/21" in resp.text
     assert resp.headers["allow"] == "POST, DELETE"