fleet-memory/hindsight-integrations/cloudflare-oauth-proxy

Cloudflare OAuth Proxy for Self-Hosted Hindsight

An OAuth 2.1 proxy that connects cloud-based MCP clients (such as claude.ai, Claude Code, and Codex) to a self-hosted Hindsight instance. Built on Cloudflare Workers using the @cloudflare/workers-oauth-provider library.

Why

Cloud-based MCP clients require an OAuth 2.1 flow to connect to remote MCP servers. Self-hosted Hindsight instances typically sit behind a private network or Cloudflare Tunnel, and don't natively expose an OAuth endpoint. This Worker bridges that gap: it handles the OAuth dance on a public domain, authenticates the user with a simple password gate, and proxies authenticated MCP traffic to your Hindsight origin through a Cloudflare Tunnel.

Architecture

Cloud MCP Client (claude.ai, Claude Code, Codex)
        |
        | HTTPS + OAuth 2.1
        v
Cloudflare Worker (this proxy)
   - OAuth 2.1 authorization server
   - Dynamic client registration (RFC 7591)
   - PKCE (S256 only)
   - CORS restricted to allowlisted origins
        |
        | HTTPS + Cloudflare Tunnel
        v
Self-hosted Hindsight (Docker)

Prerequisites

• A Cloudflare account with a domain
• A running self-hosted Hindsight instance (see self-hosting quickstart)
• A Cloudflare Tunnel exposing your Hindsight instance
• Node.js (v18+)

Setup

1. Install dependencies

cd hindsight-integrations/cloudflare-oauth-proxy
npm install

2. Configure wrangler.toml

Copy the included wrangler.toml and update the placeholder values:

• HINDSIGHT_ORIGIN: Your Cloudflare Tunnel origin URL (e.g., https://hindsight-origin.yourdomain.com)
• kv_namespaces.id: Create a KV namespace via npx wrangler kv namespace create OAUTH_KV and paste the returned ID
• routes.pattern / routes.zone_name: Your public-facing domain for the proxy

3. Set secrets

npx wrangler secret put SESSION_SECRET       # Password for the login page
npx wrangler secret put PROXY_SECRET         # X-Proxy-Secret header value (must match your origin WAF rule)
npx wrangler secret put HINDSIGHT_API_TOKEN  # Bearer token for the Hindsight API
npx wrangler secret put ALLOWED_EMAIL        # Your email (used as the OAuth user identity)

4. Deploy

npm run deploy

5. Secure your origin

Add a WAF rule on your Cloudflare Tunnel origin hostname to block requests that don't carry the correct X-Proxy-Secret header. This ensures only the Worker can reach your Hindsight instance.

Connecting clients

Once deployed, add the Worker URL as a remote MCP server in your client:

• claude.ai: Settings > MCP Servers > Add > enter https://hindsight.yourdomain.com/mcp
• Claude Code: claude mcp add hindsight-remote https://hindsight.yourdomain.com/mcp --transport http
• Codex: Configure via the MCP settings with the same URL

On first connection, you'll be redirected to a login page. Enter the SESSION_SECRET password to authorize. This only needs to happen once per OAuth session.

Secrets reference

Secret	Purpose
SESSION_SECRET	Password shown on the login page to authorize a session
PROXY_SECRET	Value sent as X-Proxy-Secret header to the origin (for WAF validation)
HINDSIGHT_API_TOKEN	Bearer token for authenticating with the Hindsight API
ALLOWED_EMAIL	Your email address, used as the OAuth user identity

Security notes

• CORS is restricted to claude.ai origins by default. To support additional clients (e.g., ChatGPT), add their origins to the ALLOWED_ORIGINS set in src/index.ts.
• PKCE is enforced with S256 only (plain PKCE is not advertised).
• OAuth state is stored in Cloudflare KV with a 5-minute TTL.
• The proxy strips the client's Authorization header and replaces it with the configured HINDSIGHT_API_TOKEN before forwarding to the origin.