bee-ai-auth-mcp

Home / Set up

Self-host guide

Run your own instance.

About fifteen minutes. You'll need a Cloudflare account on the Workers Paid plan (the bridge runs as a Container), the wrangler CLI, a GitHub account, and a Bee token (we'll show you how to get one). Your Bee token never leaves your own deployment — it's pasted at the consent screen, not stored as a secret.

  1. Clone and install

    # grab the code, install dependencies
git clone https://github.com/klappy/bee-ai-auth-mcp
cd bee-ai-auth-mcp && npm install

  2. Create the grant store

    One KV namespace holds the encrypted OAuth grants. Paste the id it prints into wrangler.jsonc under the OAUTH_KV binding, replacing the placeholder.

    wrangler kv namespace create OAUTH_KV

  3. Register a GitHub OAuth App

    GitHub → Settings → Developer settings → OAuth Apps → New OAuth App. This is the identity provider for the login leg.

    Application name
    Anything, e.g. bee-ai-auth-mcp
    Homepage URL
    https://<your-worker>
    Callback URL
    https://<your-worker>/callback — must be exact

    Register, copy the Client ID, and generate a Client secret. Store both as Worker secrets:

    wrangler secret put GITHUB_CLIENT_ID
wrangler secret put GITHUB_CLIENT_SECRET

    OAuth App, not GitHub App

    GitHub offers two things under Developer settings. Pick OAuth Apps — bee only reads your login, so it doesn't need a GitHub App's installations, permissions, or webhooks.

  4. Get your Bee token (you paste it after deploy)

    There's no Bee secret to set — your token is captured at the consent screen when you connect, and held only in your own encrypted grant. To obtain one: in the Bee iOS app, unlock Developer Mode (tap the app Version 5x); then on a computer with Node:

    npm i -g @beeai/cli
bee login --qr   # approve the scan in your Bee app
security find-generic-password -s bee-cli -a token:prod -w   # prints your token (macOS); or: cat ~/.bee/token-prod

    Hold onto that token if you take the paste route — but you usually won't need it: the consent screen offers one-tap QR pairing. Scan (or tap the link if you're already on your phone), approve in the Bee app, and the relay captures the token directly into your encrypted grant. Heads-up: the approval presents as the Bee CLI — the relay performs the CLI's pairing handshake server-side under the CLI's registered app id, which is fine for self-hosting; a relay-registered app id remains the gate for a public/multi-tenant relay. The paste path above stays as the fallback.

  5. Set your allow-list

    In wrangler.jsonc set ALLOWED_GITHUB_LOGIN to your GitHub username — the instance denies every login until you do. Bee's API host (BEE_UPSTREAM/BEE_SNI), the BEE_BRIDGE Container, and Bee's CA roots (bridge/bee-ca.pem) are already committed, so there's nothing else to fill in.

    Keep config in the file, not the dashboard

    These are config vars, not secrets — a dashboard value gets reset to the file's value on every deploy. Set them in wrangler.jsonc so they stick. (Secrets, by contrast, persist across deploys.)

  6. Deploy by pushing

    Connect the repo to Cloudflare Workers Builds, then just push: a push to main deploys to prod (and builds the bridge container image); a branch push is a preview. No manual wrangler deploy.

    git push origin main

  7. Connect, paste, and check

    Add your worker URL as a custom connector in Claude, approve the GitHub login, then paste your Bee token at the consent screen. Run whoami — it returns your Bee identity through the bridge. The Phase-2 read surface (bee_docs + bee_read, read-only) is also available.

Troubleshooting

Clicking "Connect" 404s on GitHub

The relay is redirecting to GitHub with an empty client_id — meaning GITHUB_CLIENT_ID isn't set. Set the two GitHub secrets (step 3). You can confirm the fix by checking that /authorize redirects to a real client_id rather than undefined.

"Not authorized" after logging in

The login worked, but your username isn't on the allow-list. Set ALLOWED_GITHUB_LOGIN to your GitHub login in wrangler.jsonc and redeploy.

whoami returns a 502

The bridge couldn't reach Bee. Most often BEE_UPSTREAM/BEE_SNI point at the wrong host — they must be Bee's real direct-API host (from bee status), and that host's cert must chain to bridge/bee-ca.pem. The first call also cold-starts the container, so if the very first attempt hiccups, retry once.

whoami says "Grant has no Bee credential"

Your connector grant predates the consent step. Disconnect and reconnect — the consent screen will then capture your Bee token.

Config values are empty after a deploy

ALLOWED_GITHUB_LOGIN, BEE_UPSTREAM, or BEE_SNI reset to blank? They're vars — put the real values in wrangler.jsonc, not just the dashboard, so each deploy keeps them.

Optional — a custom domain

In the Cloudflare dashboard: your Worker → Settings → Domains & Routes → Add Custom Domain. Cloudflare provisions the DNS record and cert automatically if the domain's zone is on your account.

Full detail lives in the repo's README and the connect & token guide.