| name | live-connector |
| description | Expose the local connector gateway over a free Cloudflare quick-tunnel (auth OFF) so a claude.ai or ChatGPT custom connector can reach it, and hand the human the public URL. Use this for Part 5 whenever someone wants to run their connector live, get the connector URL, (re)start or refresh the tunnel, or take it down. This is the auth-OFF demo path (AUTH_DISABLED=1); real OAuth + a real sign-in service is the AI Identity course. |
Live connector — a public tunnel for the Part 5 demo (auth OFF)
This brings the human's local gateway up as a public HTTPS URL that Anthropic's / OpenAI's
cloud can reach, so they can add it as a custom connector in claude.ai and use their whole app.
It is thin orchestration over cloudflared + the gateway + .env — no new server, no real
sign-in service. This is the auth-OFF demo path. Real, multi-user OAuth is the AI Identity
course; do not stand up an authorization server here.
The model: auth OFF, tunnel to port 8000
- Auth is OFF for this demo:
.env has AUTH_DISABLED=1, so the gateway skips OAuth, returns
no 401, and begin_session uses the fixed DEV_SUB. claude.ai accepts a no-auth remote MCP URL
(OAuth is optional in its Add-custom-connector dialog), so this is enough to connect.
- The gateway must run on
127.0.0.1:8000 (uv run python -m connector_app.server). The tunnel
is pinned to that port.
- A Cloudflare quick-tunnel URL is ephemeral — new every start. Start the tunnel, read its URL,
hand it over; if you restart it, the URL changes and the human re-adds it in claude.ai.
Turn it ON (go live)
Run from the repo root. Run the long-lived ones (cloudflared, the server) as background
processes; the waits/checks are foreground.
-
Preflight — install cloudflared if missing (covers macOS, Windows, Linux/WSL). On Windows,
run these under WSL or Git Bash (the heredocs and pkill need a POSIX shell; in native
PowerShell stop processes with taskkill /IM cloudflared.exe /F and taskkill /IM python.exe /F):
command -v cloudflared >/dev/null || {
echo "cloudflared missing — installing…"
if command -v brew >/dev/null; then brew install cloudflared
elif command -v winget >/dev/null; then winget install --id Cloudflare.cloudflared -e --silent
elif command -v choco >/dev/null; then choco install cloudflared -y
elif command -v scoop >/dev/null; then scoop install cloudflared
elif command -v apt-get >/dev/null; then
curl -fsSL https://pkg.cloudflare.com/cloudflare-main.gpg | sudo tee /usr/share/keyrings/cloudflare-main.gpg >/dev/null
echo "deb [signed-by=/usr/share/keyrings/cloudflare-main.gpg] https://pkg.cloudflare.com/cloudflared any main" \
| sudo tee /etc/apt/sources.list.d/cloudflared.list >/dev/null
sudo apt-get update -qq && sudo apt-get install -y cloudflared
else echo "Install cloudflared manually: https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/" >&2; fi
}
[ -f .env ] || cp .env.example .env
-v cloudflared && -v uv
What to hand the human (so they can connect)
- Connector URL:
$URL/mcp (changes every tunnel start).
- In claude.ai: Settings → Connectors → Add custom connector → paste
$URL/mcp → Add.
No OAuth, no client_id, no Advanced settings — auth is off. Then ask the app to do its job; open a
new chat and confirm the state carried over. Re-add (not edit) when the URL changes.
Tell the human the truth (do not skip this)
- Open door. With auth off, anyone who has the tunnel URL can reach the tools and the Neon DB
while it is up, and every caller is
DEV_SUB. It is a personal demo, never a service.
- Take it down when done:
pkill -f "cloudflared tunnel"; pkill -f "connector_app.server".
- Real sign-in is next. Multi-user identity (real OAuth + a real authorization server) is the
AI Identity course; that is when auth goes back on and strangers can actually sign in.
Turn it OFF again (back to the secure default)
python3 -c "import re;p='.env';s=open(p).read();open(p,'w').write(re.sub(r'(?m)^AUTH_DISABLED=.*$','AUTH_DISABLED=0',s))"
pkill -f "cloudflared tunnel"; pkill -f "connector_app.server"
Things that bite (so you don't relearn them)
- The tunnel URL is ephemeral — every
cloudflared start gives a new hostname; the human re-adds
it in claude.ai.
421 on every tunneled request → the --http-host-header 127.0.0.1:8000 flag is missing.- Server on the wrong port → the gateway must bind
127.0.0.1:8000; the tunnel is pinned to it.
- A stale
cloudflared can stay alive after its edge dies — always pkill and restart clean
rather than trust an existing tunnel.
