Under the hood — bee-ai-auth-mcp

The stack

Nothing in the auth or transport layer is hand-rolled. The Worker composes three proven pieces and adds a thin Bee client:

workers-oauth-provider: The OAuth 2.1 surface for MCP clients — dynamic client registration, PKCE, and encrypted grant storage in KV.
@modelcontextprotocol/sdk: MCP protocol framing, capability negotiation, and tool transport.
agents: Cloudflare's runtime for a Workers-hosted remote MCP endpoint.
src/bee.ts: The only bespoke part: a read-only client for Bee's /v1/* API.

The provider wraps the whole Worker. Requests to /mcp go to the MCP API handler; everything else (identity, health) goes to the default handler. The OAuth endpoints — /authorize, /token, /register, and /.well-known/oauth-authorization-server — are served by the provider itself.

Leg one — you ↔ the relay live

This leg proves you're allowed to use the instance. It's a standard OAuth web flow with GitHub as the upstream identity provider:

Your MCP client registers itself (dynamic client registration) and opens /authorize.
The relay 302-redirects to GitHub's /login/oauth/authorize with the instance's GITHUB_CLIENT_ID and a callback of https://<your-worker>/callback.
You approve on GitHub. GitHub returns to /callback with a code.
The relay exchanges the code for a short-lived GitHub token, reads only your login from /user, then discards the token.
Your login is checked against ALLOWED_GITHUB_LOGIN. Pass, and the provider issues the relay's own OAuth token to your client. Fail, and you get a plain "not authorized" page.

GitHub here is identity only — no repository scope, no data access. The relay never stores your GitHub token; it reads a username and lets it go.

Why an OAuth App, not a GitHub App

The sibling git-repo-auth uses a GitHub App because it mints repository tokens. bee only needs to read a login, so a plain GitHub OAuth App is the right, smaller primitive. Its client_id and client_secret are the two secrets this leg needs.

Leg two — the relay ↔ Bee gated

This leg carries your Bee credential to Bee. In Phase 1 (Model A, self-host) the credential is your own Bee token, stored as a Worker secret — not collected per user, not custodied for anyone else. The relay reaches exactly one confirmed endpoint, GET /v1/me, behind the whoami tool.

The private-CA seam

A Cloudflare Worker's fetch trusts only publicly-trusted certificates, and there's no per-request CA override. Bee's docs indicate a private CA for the direct API. So this call works if and only if Bee's real API base presents a public cert — otherwise it fails at TLS and the path is Workers VPC (Origin-CA) or mTLS. That reachability check, run from a non-proxied environment, is the open Phase-1 tripwire.

What's stored

The only persistent state is the OAuth provider's grants in the OAUTH_KV namespace. Grant props are encrypted per-grant with key material derived from the token itself — token-derived, not KMS-backed. A storage-only leak therefore reveals metadata, not usable credentials. The Bee bearer never appears in logs, URLs, errors, or tool output; errors return a status and a generic message, never the request or the token.

The MCP surface

Tools are added deliberately, against confirmed endpoints only:

Tool / endpoint	Status	Notes
whoami → /v1/me	gated	Wired; live once reachability is confirmed.
/v1/conversations	phase 2	Confirmed in Bee's docs; read-only, paginated, size-capped.
/v1/search/conversations	unconfirmed	Not in Bee's public docs — confirm-or-drop against the live API first.
/v1/changes	unconfirmed	Same — frozen out of the tool surface until verified.

Tiers

Tier 1 (Model A, self-host) is what ships: one deployment, one operator, zero third-party custody. Tier 2 (hosted, multi-tenant) is deferred — without an upstream minting primitive it would mean storing many users' long-lived Bee tokens, the exact honeypot self-host avoids. The roadmap covers why, and the security model covers the custody trade in full.

Read the source on GitHub →