Connecting Claude.ai to HA MCP Server behind Cloudflare Zero Trust (with OAuth, WAF & Bot Protection)

[Calcoon]

Hello,
I've spent a few hours integrating the ha-mcp server into Claude.ai using a Cloudflare Tunnel (cloudflared), Cloudflare Zero Trust (Access), and the built-in OAuth (Beta) feature of the Webhook Proxy for HA MCP addon.
If you are protecting your Home Assistant instance with Cloudflare Access, WAF Custom Rules (like Geo-Blocks: US), and Cloudflare Bot Protection (such as "Block AI training bots" / AI Labyrinth), Claude.ai will fail to connect with errors like Authorization with the MCP server failed (with ofid_ reference codes) and you will see no logs in your Home Assistant addon.
Here is the complete guide on how to configure Cloudflare to make it work seamlessly and securely.

---

My Setup / Prerequisites

• Home Assistant is hosted locally and is only accessible from the outside through a Cloudflare Tunnel (cloudflared) protected by Cloudflare Zero Trust (Access) requiring authentication (and optionally WAF rules like Geo-Blocking).
• The Webhook Proxy for HA MCP addon has OAuth (Beta) enabled.

---

The Problem

During the OAuth handshake, Claude's backend servers (originating from the US) need to reach multiple endpoints on your domain, not just the webhook URL.
Additionally, Cloudflare's Bot Management (which serves the "AI Labyrinth" to Python/HTTPX user agents) and any WAF Custom Rules (such as Geo-Blocks) will identify Claude's backend traffic (User-Agents like Claude-User or python-httpx) as unauthorized and block them.
Here is the step-by-step solution to bypass security checks only for the required MCP/OAuth endpoints, keeping the rest of your Home Assistant instance fully protected.

---

Step 1: Configure Cloudflare Access (Zero Trust)

You must allow Claude's servers to bypass your Cloudflare Access authentication screen for all the endpoints used during the handshake.

1. Go to your Cloudflare Zero Trust Dashboard -> Access -> Applications.
2. Edit your Bypass Application (or create one) with Action: Bypass and Include: Everyone.
3. Under Destinations, you must add all 5 of the following paths (change ha.yourdomain.com to your domain):
   • yourdomain.com/api/webhook/mcp_*
   • yourdomain.com/api/mcp_proxy/*
   • yourdomain.com/token
   • yourdomain.com/.well-known/*
   • yourdomain.com/register
4. Save the application.

---

Step 2: Configure Cloudflare WAF (Custom Rules)

Even if you bypass Zero Trust, Cloudflare's Firewall (WAF) and Bot Protection (AI Labyrinth / Block AI training bots) will block the US-based requests. We need to create a "Skip" rule to bypass these checks for the MCP paths.

1. In the Cloudflare Dashboard, go to Security rules -> Custom rules (or Security -> WAF -> Custom rules).
2. Click Create rule and name it Allow Claude MCP Webhook.
3. Click Edit expression next to the expression builder and paste this code:

   (http.request.uri.path contains "/api/webhook/mcp_") or (http.request.uri.path contains "/api/mcp_proxy/") or (http.request.uri.path contains "/.well-known/") or (http.request.uri.path eq "/token") or (http.request.uri.path eq "/register")

4. Under Choose action, select Skip.
5. Under WAF components to skip, check all available boxes, especially:
   • All remaining custom rules (this bypasses your Geo-Block rule for these paths)
   • WAF managed rules
   • Super Bot Fight Mode / Bot Management (this bypasses the "AI Labyrinth" bot blocker)
6. Under Place at, set select order to 'First' (this ensures the rule is placed at Position 1, executing before any Geo-Blocks or other custom rules).
7. Save and deploy the rule.

---

Step 3: Connect Claude.ai

1. Go to Claude.ai -> Settings -> Connectors -> Add custom connector.
2. Paste your unique Webhook Proxy URL (e.g., https://yourdomain.com/api/webhook/mcp_xxxxxx).
3. Under Advanced settings, enter the OAuth Client ID and OAuth Client Secret generated in your Webhook Proxy addon logs.
4. Click Connect, click Allow on the HA consent screen, and you are good to go!

---

Important

Make sure to keep your Webhook URL, OAuth Client ID, and Client Secret safe! Treat them like passwords.
Note: I'm a tech noob, so I'm very open to feedback and suggestions on how to make this setup even more secure or efficient!
Hope this saves someone else a few hours of debugging!

PS: I've wrote this with AI, my english isn't the best - but it's about the message! 😄

[kingpanther13]

Thanks for this, a lot of people have been having trouble with connecting to us via Cloudflare. I will see if I can add some of this into our guides or something somewhere.

[stradaconsulting]

Thank you so much for this. This solved the issues I was having.