refd MCP server

refd

Open-source AI search monitoring — track how AI answers talk about any brand: visibility, mentions, citations, and rank across ChatGPT, Perplexity, Gemini, Google AI Mode, and Google AI Overviews. Use the hosted app at refd.ai or self-host the whole stack.

A Bun-workspace monorepo of three independently deployed Cloudflare Workers: apps/api (api.refd.ai) — the Hono API, OAuth, remote MCP, daily cron, and queue consumer, holding every binding; apps/dashboard (dash.refd.ai) — the React SPA as an assets-only Worker; apps/web (refd.ai) — the static Astro public site. Shared runtime-neutral code lives in packages/core. Data via BrightData (dataset scrapers + SERP API), stored in D1 (Drizzle) with gzipped raw payloads in R2.

refd also exposes the same workspace intelligence to AI agents through a remote MCP connector. Its default data:read scope is read-only; the optional data:write scope adds the bounded setup lifecycle, can start one onboarding report, and can revoke the connection with explicit confirmation. The hosted guide lives at refd.ai/agents; the MCP connector guide covers Claude, Claude Code, ChatGPT, generic clients, personal access tokens for headless agents, and self-hosting setup.

One click from the guide installs it in Cursor or VS Code — or claude mcp add-json refd '{"type":"http","url":"https://api.refd.ai/mcp"}'. Headless agents use a personal access token from Settings → Personal access tokens instead of OAuth.

How it works

Accounts hold workspaces; each workspace tracks one brand — its competitors, its prompt set, its runs. A daily cron creates an idempotent run for every workspace eligible for scheduled monitoring, then fans out queue messages: one batch-snapshot trigger per dataset surface × sample (trigger → notify → fetch, with a backstop poll), plus one sync SERP call per prompt × sample for AI Overviews. Every answer is scored for every tracked entity (mentioned / cited / first-mention position), and the raw payload is archived gzipped in R2. A missing AI Overview is recorded as a valid "no AIO shown", not a failure. Run dispatch persists immutable launch plans and resumes with bounded backoff. Storage converges under queue redelivery, but BrightData has no idempotency key, so a crash after provider acceptance can repeat paid work.

Develop

bun install
bun run dev    # applies local migrations, then runs all three Workers behind
               # Caddy on same-site subdomains over real HTTPS

Register on the login screen (business email + password ≥ 8 chars) — your first workspace is created automatically and drops you into a resumable setup wizard: name your brand, let it draft your description from your site, pick competitors and prompts, choose engines, then watch the first report fill in live. Every AI step falls back to typing it yourself. Standard accounts can create up to five workspaces, keep up to 25 active prompts in each, and enable up to three AI surfaces. Emails in ADMIN_EMAILS have no workspace or active-prompt cap and can enable all available surfaces.

Shortened. The full README is on GitHub.