Shola Jegede - freeCodeCamp.org

How to Build an AI-Powered, Local-First Chrome Extension That Turns Your Browsing History into an Intent Map

Shola Jegede — Fri, 19 Jun 2026 17:14:43 +0000

Your browser remembers every page you've ever opened, but it has no idea why you opened any of them.

You might spend three days comparing laptops across a dozen tabs, get distracted, come back a week later, and your history just shows a flat list of timestamps and titles, with no sense that those visits were one thing, a decision you started and never finished.

In this tutorial, you'll build openloops, an open-source, local-first Chrome extension that fixes this by scanning your browsing history and grouping it into "intent threads" – the decisions, research, and open questions you keep coming back to – then scoring each one for how alive it still is. Optionally, it also uses Claude to label those threads in plain language, suggest a concrete next step, and power a chat assistant you can ask "what should I close this week?"

By the end, you'll have built:

A Manifest V3 Chrome extension with a service worker and a full-tab dashboard
A local pipeline that captures, cleans, segments, and clusters browsing history entirely in IndexedDB
A clustering algorithm tuned and debugged on real (messy) browsing data
An AI labeling layer using Claude, with a grounding step that uses brand data from context.dev
A chat assistant that reasons across your threads and tells you what to do next
A polished dashboard with onboarding, a design system, and a working pipeline status machine

Everything runs on-device, and the only network calls are optional and opt-in, made with your own API keys.

What You'll Build
Prerequisites
How openloops Is Structured
- The shared types
- The manifest
How to Scaffold the Extension
How to Capture Your Browsing History
How to Turn Noise into Sessions
How to Cluster Sessions into Intent Threads
How to Clean Up Self-Referential Noise
How to Label Threads with Claude
How to Ground Labels with context.dev
How to Design the Dashboard
How to Build the AI Assistant
What You've Built, and Where to Take It
Resources

What You'll Build

On first run, openloops greets you with a centered welcome screen that walks you through the three pipeline steps:

Once you've scanned your history, built sessions, and built the intent map, your browsing reorganizes into status-grouped threads: active, stalled, and dormant. Each one has a confidence score, a plain-language summary, a concrete next step, and a Resume button that reopens the exact pages you left off on. The right column holds a chat assistant grounded in your own threads:

That assistant response reasons across the user's actual threads, ranking them by how easy they are to close against how much of a real decision they still need. It also explains why, which is the most novel part of this build, and depends on the context.dev grounding step you'll add later in this tutorial.

Prerequisites

To follow along, you'll need:

Node 18+ and a Chromium-based browser (Chrome, Brave, Edge, and so on).
Comfort with TypeScript and React. You don't need to be an expert, but you should be comfortable reading hooks and async/await.
Basic familiarity with IndexedDB is helpful but not required, as you'll learn what you need as you go.

Two parts of this build are optional and require your own API key, each with a free tier:

An Anthropic API key (from platform.claude.com) for AI labeling and the chat assistant
A context.dev API key (from context.dev) for the brand-grounding step

You can build and use the entire core pipeline, capture, clustering, scoring, without either key, since both are additive layers on top of it.

How openloops Is Structured

Before writing any code, it helps to see the whole shape of the thing. Every stage of openloops reads from one IndexedDB store and writes to the next:

chrome.history (backfill) ──┐
chrome.tabs.onUpdated (live)─┴─→ raw_events
                                     │  noise filter
                                     ▼
                                  sessions
                                     │  ambient detection + clustering + scoring
                                     ▼
                               intent_threads
                                     │
                                     ▼
                              React dashboard
                                     │  optional, opt-in
                                     ├──→ brand enrichment   (context.dev)
                                     └──→ AI labeling + next step (Claude)
                                              │
                                              ▼  optional, opt-in
                                        AI assistant chat (Claude)

Each stage is a separate module under src/pipeline/, and each one is independently inspectable: you can open Chrome DevTools, look at raw_events, sessions, or intent_threads directly in the Application tab, and rebuild any single stage without touching the others.

The Shared Types

Every stage consumes and produces the same handful of TypeScript interfaces, defined once in src/types.ts:

// Shared TypeScript interfaces for the openloops pipeline.
// Each stage of the pipeline consumes and produces these types.

export interface RawEvent {
  id: string;
  url: string;
  domain: string;
  title: string;
  visitedAt: number;         // epoch ms
  source: "backfill" | "live";
}

export interface Session {
  id: string;
  events: RawEvent[];
  startedAt: number;
  endedAt: number;
  domains: string[];
  keywords: string[];
}

export interface IntentThread {
  id: string;
  title: string;
  summary?: string;
  nextStep?: string;   // one concrete action to move the thread forward
  sessions: Session[];
  type: "buying" | "research" | "planning" | "learning" | "unclassified";
  confidence: number;        // 0-1
  status: "active" | "stalled" | "dormant";
  firstSeen: number;
  lastSeen: number;
  distinctDays: number;
  signals: string[];
}

export interface Brand {
  domain: string;
  name: string;
  description: string;
  industry: string;
  logoUrl: string;
  brandColor: string;
}

Most fields on IntentThread, confidence, status, signals, and distinctDays get filled in by pure local heuristics later in this guide, when you cluster and score threads. summary and nextStep stay undefined until the optional AI labeling step, covered after that, fills them in.

This is the pattern that makes the whole project work: the core data model functions on its own, and AI makes it richer.

The Manifest

openloops is a Manifest V3 extension with three permissions and three host permissions:

{
  "manifest_version": 3,
  "name": "openloops",
  "version": "0.0.1",
  "description": "Reconstruct your browsing history into an AI-labeled map of intent threads: active decisions, stalled research, open questions. Fully local.",

  "permissions": ["history", "tabs", "storage"],
  "host_permissions": [
    "https://api.anthropic.com/*",
    "https://api.context.dev/*",
    "https://logos.context.dev/*"
  ],

  "background": {
    "service_worker": "src/background.ts",
    "type": "module"
  },

  "options_page": "src/dashboard/index.html",

  "icons": {
    "16": "icons/icon16.png",
    "32": "icons/icon32.png",
    "48": "icons/icon48.png",
    "128": "icons/icon128.png"
  },

  "action": {
    "default_title": "openloops",
    "default_icon": {
      "16": "icons/icon16.png",
      "32": "icons/icon32.png"
    }
  }
}

The permissions, host permissions, and options_page entry each carry specific weight:

permissions: ["history", "tabs", "storage"] are the only permissions the core pipeline needs. history reads your browsing history for the backfill, tabs lets the service worker observe new page loads and lets "Resume" reopen tabs, and storage is where API keys and preferences live.
host_permissions are separate, and only matter if you use the optional AI features. They're what let the dashboard make fetch() calls to Anthropic and context.dev without hitting CORS errors.
options_page points at the dashboard. Setting it this way, instead of a default_popup, means clicking the toolbar icon opens the dashboard as a full browser tab rather than a tiny popup, which matters once you're looking at a multi-column layout with status-grouped cards and a chat panel.

How to Scaffold the Extension

Start with Vite and the CRXJS plugin, which compiles a Manifest V3 extension with hot module reloading:

npm create vite@latest openloops -- --template react-ts
cd openloops
npm install @crxjs/vite-plugin idb react-markdown

Your vite.config.ts wires CRXJS to your manifest.json, and from there, Vite handles compiling src/background.ts to a real .js file that Chrome can load (a raw .ts service worker path in the manifest will fail with a registration error, which we'll debug in the next section).

The dashboard's entry point is a standard React 18 root:



  
    
    
    openloops

import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import "./app.css";
import App from "./App";

createRoot(document.getElementById("root")!).render(
  
    
  
);

Build it, then load it as an unpacked extension:

npm run build

In Chrome, go to chrome://extensions, enable Developer mode, click Load unpacked, and select the dist/ folder. With nothing else built yet, clicking the toolbar icon should open a blank dashboard tab, and the service worker (visible from the extension card's "service worker" link) should log [openloops] Extension installed. on install.

With that foundation in place, it's time to start filling raw_events with your actual browsing history.

How to Capture Your Browsing History

Every record in openloops starts life as a RawEvent, the type you saw earlier: a URL, a domain, a title, a timestamp, and a source of either "backfill" or "live".

Two pipelines populate it:

A one-time backfill that reads your last 14 days of chrome.history on demand
Live capture, which listens for new page loads from this point forward

Both paths share a handful of small helpers and write through the same IndexedDB layer, so it's worth building those first.

A Few Shared Helpers

Create src/lib/util.ts:

export function isHttpUrl(url: string): boolean {
  return url.startsWith("http://") || url.startsWith("https://");
}

export function extractDomain(url: string): string {
  try {
    const { hostname } = new URL(url);
    return hostname.replace(/^www\./, "");
  } catch {
    return url;
  }
}

export function isLocalHost(domain: string): boolean {
  if (domain === "localhost" || domain === "127.0.0.1") return true;
  if (domain.endsWith(".local")) return true;

  const octets = domain.split(".");
  if (octets.length === 4 && octets.every((o) => /^\d{1,3}$/.test(o))) {
    const [a, b] = octets.map(Number);
    if (a === 10) return true;
    if (a === 172 && b >= 16 && b <= 31) return true;
    if (a === 192 && b === 168) return true;
  }

  return false;
}

export function hashId(url: string, visitedAt: number): string {
  const str = `\({url}|\){visitedAt}`;
  let hash = 5381;
  for (let i = 0; i < str.length; i++) {
    hash = ((hash << 5) + hash) ^ str.charCodeAt(i);
    hash |= 0;
  }
  return (hash >>> 0).toString(36);
}

Each of these four functions solves a problem you won't notice until later in the build:

isHttpUrl is the shared scheme guard used by both live capture and the backfill, and the single gate that keeps chrome://, chrome-extension://, about:, and file:// URLs out of your data entirely. Both capture paths call it before anything else.
extractDomain strips a leading www. and returns the hostname, which is a simplification: bbc.co.uk and news.bbc.co.uk wouldn't collapse to the same domain under this logic, since true registrable-domain extraction needs the Public Suffix List. If the URL is malformed, it just returns the input unchanged rather than throwing.
isLocalHost exists for one reason: when you add brand enrichment later in this guide, you'll be sending domain names to an external API. localhost:5173 or 192.168.1.50 are meaningless to that API and would just be wasted lookups, so it's better to filter them here, once, at the source. It checks for localhost, 127.0.0.1, .local hostnames, and the standard private IPv4 ranges (10.x.x.x, 172.16.x.x–172.31.x.x, 192.168.x.x).
hashId combines the URL and timestamp into a short, deterministic string using a simple hashing algorithm (djb2), so the same (url, visitedAt) pair always produces the same ID. This makes writes idempotent: re-running the backfill produces the same IDs for the same visits, so IndexedDB's put overwrites cleanly instead of duplicating, which is what makes "Scan my history" safe to click more than once.

The Database Layer (So Far)

openloops stores everything in IndexedDB via the idb wrapper, which gives you a typed, promise-based API over the raw IndexedDB calls. Create src/db/index.ts:

import { openDB, type DBSchema, type IDBPDatabase } from "idb";
import type { RawEvent } from "../types";

interface OpenloopsDB extends DBSchema {
  raw_events: {
    key: string;
    value: RawEvent;
    indexes: { by_visitedAt: number };
  };
}

const DB_NAME = "openloops";
const DB_VERSION = 1;

let _db: Promise> | null = null;

export function getDB(): Promise> {
  if (!_db) {
    _db = openDB(DB_NAME, DB_VERSION, {
      upgrade(db) {
        if (!db.objectStoreNames.contains("raw_events")) {
          const s = db.createObjectStore("raw_events", { keyPath: "id" });
          s.createIndex("by_visitedAt", "visitedAt");
        }
      },
    });
  }
  return _db;
}

export async function clearEvents(): Promise {
  const db = await getDB();
  return db.clear("raw_events");
}

export async function putEvents(events: RawEvent[]): Promise {
  if (events.length === 0) return;
  const db = await getDB();
  const tx = db.transaction("raw_events", "readwrite");
  await Promise.all([...events.map((e) => tx.store.put(e)), tx.done]);
}

export async function getAllEvents(): Promise {
  const db = await getDB();
  return db.getAllFromIndex("raw_events", "by_visitedAt");
}

export async function getEventCount(): Promise {
  const db = await getDB();
  return db.count("raw_events");
}

Four small functions round out this first version of the database layer: clearEvents wipes the store, which the backfill calls first so every scan starts from a clean snapshot. putEvents writes a batch using IDB's put, which overwrites rather than duplicates. getAllEvents returns everything sorted by visitedAt via the index. And getEventCount returns a simple count for the dashboard.

_db is a module-level singleton promise, so every part of the extension, the service worker and the dashboard alike, shares one connection. DB_VERSION starts at 1 here. As you add sessions, intent threads, and brand data in later parts, you'll add new stores guarded by if (!db.objectStoreNames.contains(...)) and bump this number. That guard means existing users upgrade safely without touching stores that already exist.

Capturing New Visits Live

The service worker is the always-on part of the extension. Create src/background.ts:

import { hashId, extractDomain, isHttpUrl } from "./lib/util";
import { putEvents } from "./db/index";
import type { RawEvent } from "./types";

chrome.runtime.onInstalled.addListener(() => {
  console.log("[openloops] Extension installed.");
});

chrome.action.onClicked.addListener(() => {
  chrome.runtime.openOptionsPage();
});

const DEDUP_MS = 3_000;
const recentCaptures = new Map();

chrome.tabs.onUpdated.addListener((tabId, changeInfo, tab) => {
  if (changeInfo.status !== "complete" || !tab.url) return;

  const url = tab.url;

  if (!isHttpUrl(url)) return;

  const last = recentCaptures.get(tabId);
  const now = Date.now();
  if (last && last.url === url && now - last.at < DEDUP_MS) {
    console.log(`[openloops] dedup skip — tab \({tabId} \){url}`);
    return;
  }

  recentCaptures.set(tabId, { url, at: now });

  const event: RawEvent = {
    id: hashId(url, now),
    url,
    domain: extractDomain(url),
    title: tab.title ?? url,
    visitedAt: now,
    source: "live",
  };

  putEvents([event]).then(() => {
    console.log(`[openloops] captured \({event.domain} — \){event.title}`);
  }).catch((err) => {
    console.error("[openloops] putEvents failed:", err);
  });
});

chrome.action.onClicked is what makes the toolbar icon open the dashboard as a tab rather than a popup, working together with the options_page entry in your manifest.

Live capture happens inside the tabs.onUpdated listener, which Chrome fires repeatedly as a page loads, redirects, and updates its title, though you should only care about the moment changeInfo.status === "complete". From there, isHttpUrl drops anything that isn't a real web page, the dedup guard collapses the duplicate "complete" events that SPAs love to fire, and the rest becomes a RawEvent with source: "live".

That dedup guard is best-effort by design: recentCaptures is a plain in-memory Map, and Chrome can suspend the service worker between events, which wipes the Map along with it. It still collapses duplicate bursts within a single waking session, just not across service worker restarts, and that's an acceptable tradeoff since hashId already makes any duplicate that slips through harmless once it reaches IndexedDB.

The final write also looks slightly unusual: putEvents([event]).then(...).catch(...) instead of await. The listener doesn't need to block on the write finishing, and the service worker stays alive long enough to complete a single IndexedDB write even if it's about to be suspended, so firing the write and moving on is enough.

That source field carries more weight than it first appears, since it's how later code distinguishes "the user actually scanned their history" from "the extension has only been open for five minutes". This matters for onboarding when you design the dashboard later in this guide.

Build and reload the extension now (npm run build, then click the reload icon on the extension card in chrome://extensions), browse a few pages, then open the service worker's DevTools by clicking "service worker" on the extension card. You'll be able to see [openloops] captured ... log lines appear as confirmation that live capture is working.

Backfilling 14 Days of History

Live capture only sees what happens after you install the extension, so to make openloops useful immediately, you also need to backfill recent history. Create src/pipeline/backfill.ts:

import { extractDomain, hashId, isHttpUrl } from "../lib/util";
import { putEvents, clearEvents } from "../db/index";
import type { RawEvent } from "../types";

const CONCURRENCY = 50;

async function visitsForItem(
  item: chrome.history.HistoryItem,
  startTime: number
): Promise {
  if (!item.url) return [];
  if (!isHttpUrl(item.url)) return [];

  const visits = await chrome.history.getVisits({ url: item.url });

  const events: RawEvent[] = [];
  for (const visit of visits) {
    if (!visit.visitTime || visit.visitTime < startTime) continue;

    events.push({
      id: hashId(item.url, visit.visitTime),
      url: item.url,
      domain: extractDomain(item.url),
      title: item.title ?? item.url,
      visitedAt: visit.visitTime,
      source: "backfill",
    });
  }

  return events;
}

export async function backfillHistory(days = 14): Promise {
  await clearEvents();

  const startTime = Date.now() - days * 24 * 60 * 60 * 1000;

  const historyItems = await chrome.history.search({
    text: "",
    startTime,
    maxResults: 100_000,
  });

  let totalWritten = 0;

  for (let i = 0; i < historyItems.length; i += CONCURRENCY) {
    const batch = historyItems.slice(i, i + CONCURRENCY);
    const batchResults = await Promise.all(
      batch.map((item) => visitsForItem(item, startTime))
    );
    const events = batchResults.flat();
    await putEvents(events);
    totalWritten += events.length;
  }

  return totalWritten;
}

backfillHistory starts by calling clearEvents and wiping the store so each run produces a clean snapshot for the chosen window. Every real visit still exists in chrome.history, so nothing is lost by starting over. It then searches with maxResults: 100_000, since the default of 100 is far too low for anyone with more than a few days of real browsing.

Each matching HistoryItem goes through visitsForItem, which skips items that Chrome returns with no url at all, a quirk of some deleted-history entries, and skips non-web URLs using isHttpUrl, before fetching that item's full visit list.

Calling getVisits here, instead of relying on search alone, matters because chrome.history.search is tempting as a single call, but it collapses every visit to a URL down to just the most recent one. If you visited the same Stack Overflow answer three times over two days while debugging something, search gives you one row, and in the next section, where you segment events into sessions, you need all three: that's the difference between "one visit, three days ago" and "a sustained debugging session."

getVisits gives you that full timestamp list, but it returns all history for a URL regardless of date range, so visitsForItem filters by startTime itself. And because chrome.history.search can return tens of thousands of items for a heavy browser history, the backfill fans out to getVisits in batches of CONCURRENCY, set to 50, rather than firing everything at once. Chrome doesn't document a hard limit on concurrent getVisits calls, but 50 in flight at a time keeps things responsive without flooding it.

Checkpoint

You can verify live capture by browsing normally and watching raw_events fill up: open chrome://extensions, click "service worker" on the openloops card, then go to the Application tab → IndexedDB → openloops → raw_events, where each row should be a RawEvent with source: "live".

backfillHistory itself doesn't have a UI yet, but you'll wire it up to a "Scan my history" button when you build the dashboard rail in Part 13. For now, it's enough that it compiles and that raw_events is filling up from live capture. In the next part you'll start turning that raw stream into something structured: sessions.

How to Turn Noise into Sessions

A real browsing history is full of activity that has nothing to do with what you were actually trying to do. An afternoon of research might be interleaved with dozens of visits to Gmail, Slack, or YouTube, along with pages whose titles are just "New Tab" or "Dashboard" because the page hadn't finished loading when the browser recorded it.

Before any of this can be grouped into something meaningful, two things need to happen: the noise needs to be filtered out, and what remains needs to be broken into sessions, contiguous stretches of activity separated by gaps in time.

This section builds both of those steps, along with a small keyword extractor that each session uses to describe what it was about, since that description is what later powers clustering.

Filtering Out Noise

Create src/pipeline/noise.ts:

import type { RawEvent } from "../types";
import { isHttpUrl, isLocalHost } from "../lib/util";

export const BLOCKED_DOMAINS: readonly string[] = [
  "mail.google.com",
  "outlook.live.com",
  "outlook.office.com",
  "calendar.google.com",
  "slack.com",
  "app.slack.com",
  "discord.com",
  "web.whatsapp.com",
  "teams.microsoft.com",
  "messenger.com",
];

export const ADULT_DOMAINS: readonly string[] = [
  "xvideos.com",
  "pornhub.com",
  "xnxx.com",
  "xhamster.com",
  "redtube.com",
  "youporn.com",
  "spankbang.com",
];

export const JUNK_DOMAINS: readonly string[] = [
  "trk.myperfect2give.com",
  "t.buenotraffic.com",
  "bwredir.com",
  "osom.saintscommunity.net",
];

const ALL_BLOCKED = [...BLOCKED_DOMAINS, ...ADULT_DOMAINS, ...JUNK_DOMAINS];

function domainIsBlocked(domain: string): boolean {
  return ALL_BLOCKED.some(
    (blocked) => domain === blocked || domain.endsWith("." + blocked)
  );
}

export const NOISE_TITLE_PREFIXES: readonly string[] = [
  "new tab",
  "new chat",
  "untitled",
  "inbox",
  "home",
  "dashboard",
  "sign in",
  "log in",
  "loading",
];

function titleIsGeneric(title: string, domain: string): boolean {
  if (title.trim() === "") return true;
  if (title.toLowerCase() === domain.toLowerCase()) return true;

  const lower = title.toLowerCase();
  return NOISE_TITLE_PREFIXES.some((prefix) => lower.startsWith(prefix));
}

export function isNoise(event: RawEvent): boolean {
  if (!isHttpUrl(event.url)) return true;
  if (isLocalHost(event.domain)) return true;
  return domainIsBlocked(event.domain) || titleIsGeneric(event.title, event.domain);
}

isNoise is the single function the rest of the pipeline calls, and it layers four checks on top of each other, each one catching a different kind of noise.

The first two checks reuse the helpers from earlier: isHttpUrl and isLocalHost drop anything that isn't a real web page or that points at a local development server, the same filters that already protect capture. Checking them again here is a deliberate belt-and-suspenders measure: if anything ever reaches raw_events without having passed through capture's checks, it still can't make it into a session.

BLOCKED_DOMAINS covers communication and productivity tools, Gmail, Slack, Discord, WhatsApp Web, and similar. Those tools that you visit constantly but that carry no research intent of their own. domainIsBlocked matches both the exact domain and any subdomain, so slack.com in the list also catches app.slack.com. ADULT_DOMAINS and JUNK_DOMAINS exist for related reasons, keeping adult content and known tracker or redirect domains out of your threads entirely.

BLOCKED_DOMAINS is a curated, static list, and later in this guide it's complemented by a second, frequency-based detector in ambient.ts. This drops any domain that shows up in nearly every session regardless of what that domain actually is.

The last check, titleIsGeneric, catches pages whose titles tell you nothing useful: an empty title, a title that's identical to the domain name, or a title that starts with a generic prefix like "New Tab", "Dashboard", "Loading...", or "Sign in". NOISE_TITLE_PREFIXES is matched against the start of the lowercased title, so "Dashboard | Vercel" gets dropped right alongside a bare "Dashboard", while a content-rich title on that same domain passes through untouched.

Extracting Keywords

Create src/pipeline/keywords.ts. This isn't NLP, just frequency counting after stopword removal. This is good enough to surface something like "typescript generics" or "react hooks" from a session of related browsing:

import { BLOCKED_DOMAINS } from "./noise";

export const STOPWORDS: ReadonlySet = new Set([
  "the", "and", "for", "with", "you", "your", "how", "what", "this", "that",
  "from", "are", "was", "not", "but", "all", "can", "has", "have", "will",
  "its", "out", "one", "get", "our", "had", "just", "about", "also", "more",
  "into", "than", "then", "when", "their", "there", "which", "would", "been",
  "his", "her", "who", "they", "she", "him", "now", "any", "way", "use",
  "using", "used", "make", "made",
  "google", "youtube", "search", "chat", "new", "home", "www", "com", "org",
  "net", "page", "site", "tab", "view", "app", "log", "sign", "login",
  "official", "free", "online", "best", "top", "open",
]);

export const PLATFORM_STOPWORDS: ReadonlySet = new Set([
  "instagram", "facebook", "youtube", "claude", "google", "linkedin",
  "twitter", "reddit", "netflix", "amazon", "gmail", "whatsapp", "tiktok",
  "messenger",
  "stories", "story", "reel", "reels", "shorts", "short", "feed", "watch",
  "video", "videos", "music", "post", "posts", "message", "messages",
  "dm", "dms", "notification", "notifications", "profile", "home", "login",
  "signin", "follow", "followers",
]);

function derivedDomainLabels(): Set {
  const labels = new Set();
  for (const domain of BLOCKED_DOMAINS) {
    const label = domain.split(".").at(-2);
    if (label) labels.add(label);
  }
  return labels;
}

const ALL_STOP_TOKENS: ReadonlySet = new Set([
  ...STOPWORDS,
  ...PLATFORM_STOPWORDS,
  ...derivedDomainLabels(),
]);

export function extractKeywords(titles: string[], max = 8): string[] {
  const freq = new Map();

  for (const title of titles) {
    const tokens = title.toLowerCase().split(/[^a-z0-9]+/);
    for (const token of tokens) {
      if (token.length < 3) continue;
      if (/^\d+$/.test(token)) continue;
      if (ALL_STOP_TOKENS.has(token)) continue;

      freq.set(token, (freq.get(token) ?? 0) + 1);
    }
  }

  return [...freq.entries()]
    .sort((a, b) => b[1] - a[1])
    .slice(0, max)
    .map(([token]) => token);
}

extractKeywords takes the page titles from a group of events and returns the handful of words that show up most often, after stripping out everything that isn't a topic. That stripping is doing more work than the name "stopwords" suggests.

STOPWORDS covers common English function words like "the" and "with", plus generic site chrome like "search", "login", and "page". On its own, this would still let through tokens like "instagram" or "reels" from a title such as "Reels · Instagram", and those tokens would then show up as keywords for that session.

That gap is what PLATFORM_STOPWORDS closes. A title like "Reels · Instagram" or "Watch - YouTube" identifies the tool you were using, not what you were doing with it. So PLATFORM_STOPWORDS strips out platform and brand names along with social media UI chrome like "stories", "feed", "dm", and "notifications". Without this list, sessions on social platforms would extract keywords like "instagram" or "watch". Those would become thread titles that quietly pull unrelated sessions together during clustering, since every social-media session would share that one meaningless keyword.

derivedDomainLabels keeps a third source of stopwords in sync automatically: for every domain in BLOCKED_DOMAINS, it takes the label immediately before the top-level domain. So mail.google.com becomes google and web.whatsapp.com becomes whatsapp. Adding a new domain to that blocklist later also prevents its name from polluting keywords, without any extra bookkeeping.

With all three sets merged once at module load into ALL_STOP_TOKENS, extractKeywords itself is straightforward: lowercase every title, split on anything that isn't a letter or digit, drop tokens shorter than three characters or made entirely of digits, and drop anything in ALL_STOP_TOKENS. Then count what's left and return the most frequent entries.

Extending the Database For Sessions

Sessions need a place to live. Earlier in this guide, src/db/index.ts defined a schema with just raw_events at version 1. We'll add a sessions store and bump the version to 2.

First, extend the schema and the upgrade callback:

import type { RawEvent, Session } from "../types";

interface OpenloopsDB extends DBSchema {
  raw_events: {
    key: string;
    value: RawEvent;
    indexes: { by_visitedAt: number };
  };
  sessions: {
    key: string;
    value: Session;
    indexes: { by_startedAt: number };
  };
}

const DB_VERSION = 2;

export function getDB(): Promise> {
  if (!_db) {
    _db = openDB(DB_NAME, DB_VERSION, {
      upgrade(db) {
        if (!db.objectStoreNames.contains("raw_events")) {
          const s = db.createObjectStore("raw_events", { keyPath: "id" });
          s.createIndex("by_visitedAt", "visitedAt");
        }
        if (!db.objectStoreNames.contains("sessions")) {
          const s = db.createObjectStore("sessions", { keyPath: "id" });
          s.createIndex("by_startedAt", "startedAt");
        }
      },
    });
  }
  return _db;
}

Then add the helper functions sessions need, alongside the raw_events helpers you already wrote. They follow the same shape: putSessions writes a batch idempotently, clearSessions wipes the store before a rebuild, getAllSessions returns everything sorted by startedAt via the index, and getSessionCount returns a total.

export async function putSessions(sessions: Session[]): Promise {
  if (sessions.length === 0) return;
  const db = await getDB();
  const tx = db.transaction("sessions", "readwrite");
  await Promise.all([...sessions.map((s) => tx.store.put(s)), tx.done]);
}

export async function clearSessions(): Promise {
  const db = await getDB();
  return db.clear("sessions");
}

export async function getAllSessions(): Promise {
  const db = await getDB();
  return db.getAllFromIndex("sessions", "by_startedAt");
}

export async function getSessionCount(): Promise {
  const db = await getDB();
  return db.count("sessions");
}

The if (!db.objectStoreNames.contains(...)) guard from earlier is what makes this safe: anyone who already has a version-1 database, with raw_events full of real data, gets the new sessions store added on top, without touching what's already there.

Segmenting Events into Sessions

A session is a contiguous block of browsing activity, with a new one starting whenever the gap between two consecutive events exceeds SESSION_GAP_MS. Create src/pipeline/sessions.ts:

import { getAllEvents, clearSessions, putSessions } from "../db/index";
import { isNoise } from "./noise";
import { extractKeywords } from "./keywords";
import { hashId } from "../lib/util";
import type { RawEvent, Session } from "../types";

const SESSION_GAP_MS = 30 * 60 * 1000;

function rankDomains(events: RawEvent[]): string[] {
  const freq = new Map();
  for (const e of events) {
    freq.set(e.domain, (freq.get(e.domain) ?? 0) + 1);
  }
  return [...freq.entries()]
    .sort((a, b) => b[1] - a[1])
    .map(([domain]) => domain);
}

function buildSession(events: RawEvent[]): Session {
  const startedAt = events[0].visitedAt;
  const endedAt = events[events.length - 1].visitedAt;

  return {
    id: hashId(events[0].url, startedAt),
    events,
    startedAt,
    endedAt,
    domains: rankDomains(events),
    keywords: extractKeywords(events.map((e) => e.title)),
  };
}

export async function buildSessions(): Promise<{ events: number; sessions: number }> {
  const allEvents = await getAllEvents();

  const meaningful = allEvents.filter((e) => !isNoise(e));

  if (meaningful.length === 0) {
    await clearSessions();
    return { events: 0, sessions: 0 };
  }

  const sessions: Session[] = [];
  let currentGroup: RawEvent[] = [meaningful[0]];

  for (let i = 1; i < meaningful.length; i++) {
    const gap = meaningful[i].visitedAt - meaningful[i - 1].visitedAt;

    if (gap > SESSION_GAP_MS) {
      sessions.push(buildSession(currentGroup));
      currentGroup = [meaningful[i]];
    } else {
      currentGroup.push(meaningful[i]);
    }
  }
  sessions.push(buildSession(currentGroup));

  const substantive = sessions.filter(
    (s) => !(s.events.length === 1 && s.keywords.length === 0)
  );

  await clearSessions();
  await putSessions(substantive);

  return { events: meaningful.length, sessions: substantive.length };
}

buildSessions does five things in order:

loads every raw event sorted by time,
drops anything isNoise flags,
walks the remaining list and starts a new session whenever the gap between two consecutive events exceeds SESSION_GAP_MS (pushing the final in-progress group once the loop ends since nothing else closes it off),
drops sessions that turned out to be a single event with no extractable keywords (usually stray page loads that never connected to anything else),
and persists the result.

Each session's domains and keywords come from rankDomains and extractKeywords running over just the events in that group. rankDomains counts how many events came from each domain and orders them by frequency, so the most-visited domain in a session comes first.

A worked example makes "walking the list" concrete. Take five events that survive noise filtering, A through E:

A  t= 0 min  "TypeScript generics - Stack Overflow"   stackoverflow.com
B  t= 5 min  "TypeScript Handbook"                    typescriptlang.org
C  t=10 min  "microsoft/TypeScript - GitHub"          github.com
   ↑ gap to D = 45 min  >  SESSION_GAP_MS (30 min)  → SPLIT HERE
D  t=55 min  "React hooks explained - YouTube"         youtube.com
E  t=60 min  "useEffect cleanup - Stack Overflow"     stackoverflow.com

As the loop walks from A to B to C, each gap is under the 30-minute limit, so all three stay in the same group. The jump from C to D is 45 minutes, which crosses SESSION_GAP_MS, so the loop closes off [A, B, C] as Session 1 and starts a fresh group with D. From D to E is only 5 minutes, so E joins D, and that group becomes Session 2 once the loop ends.

Session 1 ends up tagged with keywords like typescript and generics, while Session 2 is tagged with react and hooks, even though both sessions happened on the same day.

SESSION_GAP_MS is set to 30 minutes because that's the same default that Google Analytics and similar tools use, and it works well for most browsing patterns.

The tradeoff runs in both directions: a shorter gap produces more, smaller sessions, which gives clustering a more granular signal but risks fragmenting one continuous task into several pieces. A longer gap produces fewer, larger sessions, which risks merging activity that was actually unrelated.

30 minutes is a reasonable starting point, and it's the kind of constant you can come back and tune once you see how your own threads turn out.

Checkpoint

buildSessions doesn't have a UI yet either. It'll get wired up to a "Build sessions" button alongside "Scan my history" when you design the dashboard later in this guide.

For now, the goal is just for everything in this section to compile cleanly: src/pipeline/noise.ts, src/pipeline/keywords.ts, the updated src/db/index.ts, and src/pipeline/sessions.ts should all build without errors. getDB() should report version 2 the next time the extension reloads (visible in DevTools under Application → IndexedDB → openloops, where the database now lists both raw_events and sessions as object stores).

With sessions in place, the next section takes this structured-but-unconnected data and groups sessions together into the intent threads this whole project is named after.

How to Cluster Sessions into Intent Threads

Sessions group events that happened close together in time. But the things you're actually trying to do rarely fit inside one session. Comparing laptops might span three sessions over four days. A question you keep meaning to look into might surface for ten minutes every few days for two weeks.

This section groups related sessions together into intent threads, then scores each thread for how confident openloops is that it represents something real and how alive it still is.

Two files do this work. src/pipeline/ambient.ts detects domains that are part of your daily routine rather than any particular intent, so they don't create false similarity between unrelated sessions. src/pipeline/threads.ts does the actual clustering and scoring.

Detecting Ambient Domains

Some domains show up in almost every session regardless of what you're doing: youtube.com as background noise, github.com if you're a developer who commits daily, or claude.ai if you use it as a general assistant. If clustering compared sessions on these domains the same way it compares them on anything else, two completely unrelated sessions would look similar just because they both touched youtube.com, and everything would eventually merge into one enormous thread.

ambient.ts solves this with a frequency check: a domain is ambient if it shows up on a large enough fraction of your active days, regardless of topic.

Create src/pipeline/ambient.ts:

import type { Session } from "../types";

export const UBIQUITY_THRESHOLD = 0.6;
export const MIN_ACTIVE_DAYS = 3;

function toDay(epochMs: number): string {
  return new Date(epochMs).toDateString();
}

export function detectAmbientDomains(sessions: Session[]): Set {
  const allEvents = sessions.flatMap((s) => s.events);

  const activeDays = new Set(allEvents.map((e) => toDay(e.visitedAt)));
  const totalActiveDays = activeDays.size;

  if (totalActiveDays < MIN_ACTIVE_DAYS) {
    return new Set();
  }

  const domainDayMap = new Map>();
  for (const event of allEvents) {
    const day = toDay(event.visitedAt);
    if (!domainDayMap.has(event.domain)) {
      domainDayMap.set(event.domain, new Set());
    }
    domainDayMap.get(event.domain)!.add(day);
  }

  const ambient = new Set();
  for (const [domain, days] of domainDayMap) {
    const ubiquity = days.size / totalActiveDays;
    if (ubiquity >= UBIQUITY_THRESHOLD) {
      ambient.add(domain);
      console.log(
        `[openloops] ambient: \({domain} (\){days.size}/\({totalActiveDays} days, ubiquity=\){ubiquity.toFixed(2)})`
      );
    }
  }

  return ambient;
}

toDay collapses a timestamp down to a calendar-day string, so two events on the same day produce the same key, regardless of the exact time.

detectAmbientDomains first counts how many distinct days had any browsing activity at all – that's totalActiveDays – then builds a map from each domain to the set of days it appeared on. A domain's ubiquity is days.size / totalActiveDays, the fraction of your active days that domain showed up on. Anything at or above UBIQUITY_THRESHOLD 0.6 gets added to the returned set.

MIN_ACTIVE_DAYS exists because with only one or two days of data, almost every domain you visited would technically appear on 100% of your active days, and the detector would mark everything as ambient. Below three active days, it returns an empty set and skips detection entirely.

This approach has a real tradeoff. It correctly identifies genuinely ambient tools, but it can also suppress a domain you happened to research intensively every single day for a week, which would also cross the 60% threshold.

UBIQUITY_THRESHOLD is the knob for that tradeoff: raising it reduces false positives at the cost of letting some real ambient noise back in.

Extending the Database for Intent Threads

Threads need their own store. Bump DB_VERSION to 3 and add intent_threads, indexed by lastSeen, so the dashboard can show the most recently active threads first:

import type { RawEvent, Session, IntentThread } from "../types";

interface OpenloopsDB extends DBSchema {
  raw_events: {
    key: string;
    value: RawEvent;
    indexes: { by_visitedAt: number };
  };
  sessions: {
    key: string;
    value: Session;
    indexes: { by_startedAt: number };
  };
  intent_threads: {
    key: string;
    value: IntentThread;
    indexes: { by_lastSeen: number };
  };
}

const DB_VERSION = 3;

export function getDB(): Promise> {
  if (!_db) {
    _db = openDB(DB_NAME, DB_VERSION, {
      upgrade(db) {
        if (!db.objectStoreNames.contains("raw_events")) {
          const s = db.createObjectStore("raw_events", { keyPath: "id" });
          s.createIndex("by_visitedAt", "visitedAt");
        }
        if (!db.objectStoreNames.contains("sessions")) {
          const s = db.createObjectStore("sessions", { keyPath: "id" });
          s.createIndex("by_startedAt", "startedAt");
        }
        if (!db.objectStoreNames.contains("intent_threads")) {
          const s = db.createObjectStore("intent_threads", { keyPath: "id" });
          s.createIndex("by_lastSeen", "lastSeen");
        }
      },
    });
  }
  return _db;
}

Then add the matching helpers:

export async function putThreads(threads: IntentThread[]): Promise {
  if (threads.length === 0) return;
  const db = await getDB();
  const tx = db.transaction("intent_threads", "readwrite");
  await Promise.all([...threads.map((t) => tx.store.put(t)), tx.done]);
}

export async function clearThreads(): Promise {
  const db = await getDB();
  return db.clear("intent_threads");
}

export async function getAllThreads(): Promise {
  const db = await getDB();
  const index = db
    .transaction("intent_threads", "readonly")
    .store.index("by_lastSeen");

  let cursor = await index.openCursor(null, "prev");
  const results: IntentThread[] = [];
  while (cursor) {
    results.push(cursor.value);
    cursor = await cursor.continue();
  }
  return results;
}

export async function getThreadCount(): Promise {
  const db = await getDB();
  return db.count("intent_threads");
}

putThreads, clearThreads, and getThreadCount follow the same pattern as the sessions helpers from earlier. getAllThreads is the odd one out: instead of getAllFromIndex, which only returns ascending order, it opens a cursor on by_lastSeen in "prev" direction and walks it manually. That gives you threads ordered with the most recently active first, the order the dashboard wants for status-grouped cards.

Clustering Sessions into Threads

With ambient domains identified, src/pipeline/threads.ts now does the real work: grouping sessions into threads, then scoring and classifying each one.

The approach is greedy agglomerative clustering. Walk through sessions in chronological order, and for each one, either merge it into the most similar existing thread or start a new thread if nothing is similar enough.

Start with the imports, the tuning constants, and the similarity calculation:

import { getAllSessions, clearThreads, putThreads } from "../db/index";
import { detectAmbientDomains } from "./ambient";
import { hashId } from "../lib/util";
import type { Session, IntentThread } from "../types";

export const SIMILARITY_THRESHOLD = 0.15;
export const DOMAIN_WEIGHT = 0.5;
export const KEYWORD_WEIGHT = 0.5;

interface ThreadBuilder {
  id: string;
  sessions: Session[];
  domainSet: Set;
  keywordSet: Set;
}

function jaccard(a: Set, b: Set): number {
  if (a.size === 0 && b.size === 0) return 0;
  let intersection = 0;
  for (const item of a) {
    if (b.has(item)) intersection++;
  }
  const union = a.size + b.size - intersection;
  return intersection / union;
}

function similarity(
  session: Session,
  thread: ThreadBuilder,
  ambient: Set
): number {
  const sessionDomains  = new Set(session.domains.filter((d) => !ambient.has(d)));
  const threadDomains   = new Set([...thread.domainSet].filter((d) => !ambient.has(d)));
  const sessionKeywords = new Set(session.keywords);

  const domainScore   = jaccard(sessionDomains, threadDomains);
  const keywordScore  = jaccard(sessionKeywords, thread.keywordSet);

  return DOMAIN_WEIGHT * domainScore + KEYWORD_WEIGHT * keywordScore;
}

ThreadBuilder is a mutable accumulator used only during clustering: a thread in progress, with its sessions plus the union of all domains and keywords seen so far. jaccard is the standard set-similarity measure, the size of the intersection divided by the size of the union, returning 0 for two empty sets rather than dividing zero by zero.

similarity compares one candidate session against one in-progress thread. Before comparing domains, it filters ambient domains out of both sides, so a shared youtube.com never contributes to the score. It then computes a domain Jaccard score and a keyword Jaccard score separately, and combines them with DOMAIN_WEIGHT and KEYWORD_WEIGHT, both 0.5, giving domain overlap and keyword overlap equal say in the final number.

Next, the clustering loop itself:

function clusterSessions(
  sessions: Session[],
  ambient: Set
): ThreadBuilder[] {
  const threads: ThreadBuilder[] = [];

  for (const session of sessions) {
    let bestThread: ThreadBuilder | null = null;
    let bestScore = 0;

    for (const thread of threads) {
      const score = similarity(session, thread, ambient);
      if (score > bestScore) {
        bestScore = score;
        bestThread = thread;
      }
    }

    if (bestThread && bestScore >= SIMILARITY_THRESHOLD) {
      bestThread.sessions.push(session);
      for (const d of session.domains)  bestThread.domainSet.add(d);
      for (const k of session.keywords) bestThread.keywordSet.add(k);
    } else {
      threads.push({
        id: hashId(session.id, session.startedAt),
        sessions: [session],
        domainSet:  new Set(session.domains),
        keywordSet: new Set(session.keywords),
      });
    }
  }

  return threads;
}

clusterSessions relies on sessions already being sorted chronologically, which getAllSessions guarantees via its index. For each session, it scores against every thread built so far and keeps the best match.

If that best score clears SIMILARITY_THRESHOLD, the session merges in and its domains and keywords get folded into the thread's accumulated sets. This means that later sessions are compared against the thread's entire accumulated history rather than only its seed session. If nothing clears the threshold, the session becomes the seed of a brand-new thread.

A worked example shows how this plays out. Suppose detectAmbientDomains returned { youtube.com }, and three sessions arrive in this order:

S1: domains=[stackoverflow.com, typescriptlang.org]
    keywords=[typescript, generics, interface, mapped]

S2: domains=[stackoverflow.com, typescriptlang.org, github.com]
    keywords=[typescript, generics, utility, types]

S3: domains=[python.org, docs.python.org]
    keywords=[python, async, await, coroutine]

S1 arrives first. With no threads yet, it seeds Thread A: domainSet = {stackoverflow.com, typescriptlang.org}, keywordSet = {typescript, generics, interface, mapped}.

S2 is scored against Thread A. Neither set contains the ambient youtube.com, so nothing gets filtered out. The domain Jaccard is |{stackoverflow.com, typescriptlang.org}| / |{stackoverflow.com, typescriptlang.org, github.com}|, or 2/3 ≈ 0.667. The keyword Jaccard is |{typescript, generics}| / |{typescript, generics, interface, mapped, utility, types}|, or 2/6 ≈ 0.333. The combined similarity is 0.5 × 0.667 + 0.5 × 0.333 = 0.5, comfortably above SIMILARITY_THRESHOLD (0.15), so S2 merges into Thread A, whose sets grow to include github.com, utility, and types.

S3 is scored against Thread A. There's no overlap at all between {python.org, docs.python.org} and Thread A's domains, or between their keyword sets, so both Jaccard scores are 0 and the combined similarity is 0. That's below the threshold, so S3 seeds a new Thread B.

The result: Thread A holds the TypeScript research across two sessions, and Thread B holds the Python session on its own.

SIMILARITY_THRESHOLD is the single most consequential constant in this file, and 0.15 is lower than you might guess for a 50/50 weighted Jaccard score. A starting value like 0.3 sounds more principled. That would mean two sessions need to share roughly a third of their combined domains and keywords before they're considered part of the same thread.

Run that against real, messy browsing history, though, and it produces far too many threads: sessions that were obviously part of the same research, but didn't share quite enough keywords to clear 0.3, end up scattered across separate threads.

Dropping the threshold to 0.15 lets sessions merge on weaker but still real signal. Two sessions sharing just one domain and one keyword out of several can already cross 0.15, and the result is fewer, more coherent threads that actually match what the browsing history looks like.

This is the kind of constant you tune empirically rather than deriving it from first principles: build your threads, look at the result, and adjust.

buildThreads, covered next, prints a table of every thread's title, type, status, confidence, and top keywords specifically so you can eyeball this. If two threads obviously belong together, lower SIMILARITY_THRESHOLD. If one thread is clearly several unrelated topics glued together, raise it.

Scoring and Classifying Threads

Clustering produces groups of sessions, but a group of sessions isn't yet an IntentThread. The rest of threads.ts turns each group into something with a type, a confidence score, a status, and a set of human-readable signals explaining why.

A few small helpers come first:

export const BUYING_WORDS: readonly string[] = [
  "vs", "versus", "alternative", "alternatives",
  "comparison", "pricing", "price", "review", "reviews", "best",
];

export const LEARNING_WORDS: readonly string[] = [
  "how to", "tutorial", "tutorials", "docs", "documentation",
  "guide", "learn", "example", "examples", "crash course", "introduction",
];

const STATUS_ACTIVE_MS  = 48 * 60 * 60 * 1000;
const STATUS_STALLED_MS = 7  * 24 * 60 * 60 * 1000;

function toTitleCase(s: string): string {
  return s.charAt(0).toUpperCase() + s.slice(1);
}

function findMatches(titles: string[], wordList: readonly string[]): string[] {
  const lower = titles.map((t) => t.toLowerCase());
  const found = new Set();

  for (const word of wordList) {
    const isPhrase = word.includes(" ");
    for (const title of lower) {
      if (isPhrase) {
        if (title.includes(word)) found.add(word);
      } else {
        const tokens = title.split(/[^a-z0-9]+/);
        if (tokens.includes(word)) found.add(word);
      }
    }
  }

  return [...found];
}

function toCalendarDay(epochMs: number): string {
  return new Date(epochMs).toDateString();
}

BUYING_WORDS and LEARNING_WORDS are small vocabularies that signal intent. findMatches checks a list of page titles against one of these vocabularies, and handles single words and phrases differently: a multi-word entry like "how to" is checked as a substring, since it's specific enough that false positives are unlikely. But a single word like "review" is checked as a whole token, split out of the title on non-alphanumeric characters.

Without that distinction, "review" would match inside "overview" too, which would misclassify any thread that happened to involve an "Overview" page. toTitleCase and toCalendarDay are small formatting helpers used by the scoring function next.

That scoring function, scoreThread, is the longest function in the project, since it's where every signal collected so far gets turned into the fields on IntentThread:

function scoreThread(builder: ThreadBuilder): IntentThread {
  const { sessions, keywordSet } = builder;

  const firstSeen  = sessions[0].startedAt;
  const lastSeen   = sessions[sessions.length - 1].endedAt;

  const allEvents  = sessions.flatMap((s) => s.events);
  const totalEvents = allEvents.length;
  const daySet     = new Set(allEvents.map((e) => toCalendarDay(e.visitedAt)));
  const distinctDays = daySet.size;

  const allTitles      = allEvents.map((e) => e.title);
  const buyingMatches  = findMatches(allTitles, BUYING_WORDS);
  const learningMatches = findMatches(allTitles, LEARNING_WORDS);

  let type: IntentThread["type"];
  if (buyingMatches.length > 0) {
    type = "buying";
  } else if (learningMatches.length > 0) {
    type = "learning";
  } else if (distinctDays > 5 && sessions.length >= 3) {
    type = "planning";
  } else if (totalEvents >= 3) {
    type = "research";
  } else {
    type = "unclassified";
  }

  const age = Date.now() - lastSeen;
  const status: IntentThread["status"] =
    age < STATUS_ACTIVE_MS  ? "active"  :
    age < STATUS_STALLED_MS ? "stalled" :
    "dormant";

  const confidence = parseFloat((
    Math.min(distinctDays / 5, 1) * 0.35 +
    Math.min(sessions.length / 5, 1) * 0.25 +
    Math.min(totalEvents / 20, 1)  * 0.20 +
    (type !== "unclassified" ? 1 : 0)  * 0.20
  ).toFixed(2));

  const signals: string[] = [];

  if (distinctDays > 1)
    signals.push(`revisited across ${distinctDays} days`);
  if (type === "buying" && buyingMatches.length > 0)
    signals.push(`comparison language: ${buyingMatches.join(", ")}`);
  if (type === "learning" && learningMatches.length > 0)
    signals.push(`learning language: ${learningMatches.join(", ")}`);
  signals.push(`\({sessions.length} session\){sessions.length !== 1 ? "s" : ""}`);
  if (totalEvents > 5)
    signals.push(`${totalEvents} total events`);
  if (type === "planning")
    signals.push("sustained activity across many days");

  const ageDays = Math.floor(age / (24 * 60 * 60 * 1000));
  if (ageDays === 0)       signals.push("last active today");
  else if (ageDays === 1)  signals.push("last active yesterday");
  else                     signals.push(`last active ${ageDays} days ago`);

  const title =
    [...keywordSet].slice(0, 3).map(toTitleCase).join(" ") || "Untitled Thread";

  return {
    id: builder.id,
    title,
    sessions,
    type,
    confidence,
    status,
    firstSeen,
    lastSeen,
    distinctDays,
    signals,
  };
}

There's a lot here, so it's worth walking through each field on IntentThread in the order it's computed.

firstSeen and lastSeen come straight from the boundary sessions, since sessions arrives in chronological order from clustering. distinctDays reuses the same calendar-day collapsing as ambient.ts. This time it counts how many different days this thread's events span, regardless of how many total active days you had overall.

Classification into type is a cascade, and the order matters. Comparison language (BUYING_WORDS) is checked first, because a thread where you're comparing two frameworks is "buying" even if it also contains tutorial pages. Comparison intent is the stronger signal.

Learning language comes next. After that, planning is reserved for threads that span more than five distinct days and have at least three sessions of sustained, recurring activity rather than a single deep dive.

research is the catch-all for anything with at least three events that didn't match anything more specific, and unclassified is what's left, usually threads with too little activity to say anything confident about.

status is purely a function of how long ago lastSeen was: under 48 hours is active, under 7 days is stalled, anything older is dormant.

confidence is a weighted sum of four signals, each normalized to a maximum of 1 before weighting, so the total can't exceed 1 either. distinctDays / 5, capped at 1, contributes up to 35%, treating five or more distinct days as fully confident on that axis. sessions.length / 5, capped at 1, contributes up to 25%. totalEvents / 20, capped at 1, contributes up to 20%. And whether type is anything other than unclassified contributes the final 20% as an all-or-nothing bonus.

A thread revisited across five-plus days, across five-plus sessions, with twenty-plus events, that also classified cleanly, scores a full 1.0. A thread that's a single session with two events and no classification scores close to 0.

signals is a plain-English audit trail for the confidence score and status: it explains why a thread looks the way it does, listing things like how many days it was revisited across, what comparison or learning language was found, the session and event counts, and how recently it was last active. The dashboard surfaces these directly.

Finally, title is a placeholder: the top three keywords from the thread's accumulated keywordSet, title-cased and joined with spaces, or "Untitled Thread" if there are none.

This is deliberately weak. Later in this guide, AI labeling replaces this heuristic title, along with summary and nextStep, with something grounded in what the thread is actually about (but the thread is fully usable without that step, too).

Putting it Together

buildThreads ties everything in this section together:

export async function buildThreads(): Promise<{ sessions: number; threads: number }> {
  const sessions = await getAllSessions();

  if (sessions.length === 0) {
    await clearThreads();
    return { sessions: 0, threads: 0 };
  }

  const ambient = detectAmbientDomains(sessions);

  const builders = clusterSessions(sessions, ambient);

  const substantive = builders.filter(
    (b) => !(b.sessions.length === 1 && b.sessions[0].events.length < 3)
  );

  const threads = substantive.map(scoreThread);

  await clearThreads();
  await putThreads(threads);

  console.table(
    threads.map((t) => ({
      title:        t.title,
      type:         t.type,
      status:       t.status,
      confidence:   t.confidence,
      distinctDays: t.distinctDays,
      sessions:     t.sessions.length,
      events:       t.sessions.reduce((n, s) => n + s.events.length, 0),
      keywords:     [...new Set(t.sessions.flatMap((s) => s.keywords))].slice(0, 5).join(", "),
    }))
  );

  return { sessions: sessions.length, threads: threads.length };
}

The order here matters. detectAmbientDomains runs once, over every session, before any clustering happens, since ambient detection needs the full picture of your browsing to know what counts as "every day".

clusterSessions then produces ThreadBuilders, which get filtered before scoring: a ThreadBuilder with exactly one session and fewer than three events is almost always a stray page load that didn't merge with anything, so it's dropped rather than becoming a thread with a confidence near zero.

Everything that survives gets scored by scoreThread, persisted, and printed via console.table, which is the tuning aid mentioned earlier. If you open the service worker's console after running this, every thread is laid out in a sortable table. This is the fastest way to spot a SIMILARITY_THRESHOLD that's too high or too low.

Checkpoint

Like the previous two sections, buildThreads doesn't have a UI yet. It'll get wired up to a "Build intent map" button alongside the other two when you design the dashboard later in this guide.

For now, confirm that src/pipeline/ambient.ts, the updated src/db/index.ts, and src/pipeline/threads.ts all build without errors, and that getDB() reports version 3 the next time the extension reloads. intent_threads should now be listed alongside raw_events and sessions in DevTools.

At this point, the entire core pipeline runs end to end, locally, with no API keys involved: your browsing history becomes raw events, raw events become sessions, and sessions become scored, classified intent threads.

Everything from here is optional and additive: cleaning up a source of self-referential noise this pipeline doesn't yet handle (which you probably want to look at and incorporate), then AI labeling, brand grounding, and the dashboard that ties it all together.

How to Clean Up Self-Referential Noise

Run the pipeline a few times against your own browsing and a strange kind of thread starts appearing: one made entirely of openloops itself.

The dashboard is a web page, so every time you open it to check your threads, that page load gets captured as an event. If you're also developing the extension, your localhost dev server and any private-network addresses end up in the data too.

The tool ends up watching itself use itself, and that self-reference pollutes the intent map in two distinct ways which are worth separating.

The Two Problems

The first problem is the extension's own pages. A Chrome extension's dashboard loads from a chrome-extension:// URL, and Chrome's own internal pages use chrome://. Left unfiltered, opening the openloops dashboard ten times in an afternoon produces ten events on a chrome-extension:// origin, which cluster happily into a thread about, essentially, looking at your threads.

This is circular and useless, and because you tend to open the dashboard often while the rest of your browsing is quieter, this self-thread can score deceptively high on recency and session count.

The second problem is local development infrastructure. If you're building the extension, or any local project, your history fills with localhost:5173, 127.0.0.1:8080, and maybe LAN addresses like 192.168.1.40. These are real page visits as far as Chrome is concerned, but they carry no browsing intent in the sense openloops cares about. Worse, they'd later be sent to context.dev during brand enrichment, where they can never resolve to anything and would only waste API credits.

Both problems share a root cause: the pipeline is capturing URLs that aren't really part of your browsing in the first place. The fix is to define what counts as a real, external web page once, and apply that definition everywhere a URL or domain enters the system.

One Definition, Applied Everywhere

The two helpers that do this, isHttpUrl and isLocalHost, were written back when you first built src/lib/util.ts. We deliberately introduced them early for exactly this moment.

isHttpUrl returns true only for http:// and https:// URLs, which excludes chrome-extension://, chrome://, about:, and file:// in one stroke. isLocalHost returns true for localhost, loopback and private IP ranges, and .local hostnames.

The thing that makes them effective is consistency: the same two functions guard every entry point, so the definition of "a real page" can never drift between one part of the pipeline and another. There are three such entry points.

Live capture, in src/background.ts, calls isHttpUrl before recording anything:

if (!isHttpUrl(url)) return;

The backfill, in src/pipeline/backfill.ts, applies the same guard to every history item before fetching its visits:

if (!item.url) return [];
if (!isHttpUrl(item.url)) return [];

And the noise filter, in src/pipeline/noise.ts, checks both helpers at the very top of isNoise, before any of its domain or title rules run:

export function isNoise(event: RawEvent): boolean {
  if (!isHttpUrl(event.url)) return true;
  if (isLocalHost(event.domain)) return true;
  return domainIsBlocked(event.domain) || titleIsGeneric(event.title, event.domain);
}

Capture and backfill already screen out non-web URLs, so checking isHttpUrl a third time inside isNoise looks redundant, and in normal operation it is. The third check is a guarantee: if a stray non-web event ever reaches raw_events through some path you didn't anticipate (like a future capture mechanism, imported data, or a bug), it still can't survive into a session.

Each stage defends its own input rather than trusting that an earlier stage did its job. This is what keeps a single missed case from silently propagating all the way into the intent map.

Defending the Enrichment Boundary Too

The same isLocalHost check appears once more, in the brand enrichment step you'll build next, where domains get sent to context.dev. Even though isNoise already strips local addresses before sessionization, the enrichment function filters them again before making any network call:

const unique = [...new Set(domains)].filter((d) => !isLocalHost(d));

The reasoning is the same defense-in-depth idea, applied to a boundary where the cost of a mistake is higher. A local address that somehow reached a thread's domain list shouldn't just be useless noise in the UI. It should never leave your machine as part of an API request. Putting the filter directly at the network boundary means that guarantee holds regardless of what happened upstream.

Checkpoint

After loading the updated build, openloops should stop appearing in its own intent map. To verify, open the dashboard a handful of times, browse some real pages, then rebuild the pipeline: the chrome-extension:// self-thread should be gone, and no localhost or private-IP domains should appear in any thread's domain list.

If you inspect raw_events in DevTools, you may still see live-captured events from before this fix, since the backfill clears and rewrites events but live capture appends. Running a fresh "Scan my history" wipes and repopulates raw_events cleanly under the new rules.

With the pipeline now producing a clean intent map of genuinely external browsing, it's worth making those threads more legible.

Up to now, each thread's title is just its top three keywords stitched together, and there's no summary or suggested next step at all. The next section adds the first optional, key-gated layer: AI labeling with Claude.

How to Label Threads with Claude

A thread titled "Typescript Generics Handbook" is readable, but it's a description of the keywords – not of what you were trying to do. "Learning TypeScript's advanced type system" is the kind of label a person would actually write, and the difference between those two is the gap this section closes.

Claude reads each thread's keywords, domains, and sample page titles, and returns a real title, a one-sentence summary, a classification, and a concrete next step.

This is the first part of openloops that calls an external API and requires a key. Everything about its design is shaped by one constraint: the request has to survive real data, where a person might have thirty or forty threads, each carrying a dozen page titles.

The naïve version of this is to send all the threads in one request and ask for all the labels back. And that's exactly what the first implementation did. But it failed in a way worth walking through, because the fix is the most instructive part of the whole section.

Storing Keys Locally

Before any API call, the key needs somewhere to live. openloops keeps it in chrome.storage.local, which never syncs anywhere and never leaves the device. Create src/lib/settings.ts:

export async function getApiKey(): Promise {
  const result = await chrome.storage.local.get("anthropicApiKey");
  return (result.anthropicApiKey as string) ?? null;
}

export async function setApiKey(key: string): Promise {
  await chrome.storage.local.set({ anthropicApiKey: key });
}

The same file later grows parallel getters and setters for the context.dev key and the assistant's model and effort preferences, all following this identical shape. So it's enough to understand this one pair to understand all of them.

The First Version, and How it Broke

The first labeling implementation sent every thread to Claude in a single request: serialize all forty threads into one JSON payload, ask for a JSON array of forty labels in return, parse it, write it back. It worked perfectly with five or six threads during early testing, then silently produced nothing once a real history with thirty-plus threads went through it. There was no error or thrown exception, just threads that kept their old keyword titles as if the labeling had never run.

The cause was output token truncation. A request specifies max_tokens, the ceiling on how much the model may generate in response, and forty threads' worth of titles, summaries, and next steps is a lot of output. When the response hit that ceiling mid-generation, the JSON array was cut off partway through an opening [ and thirty complete objects followed by half of the thirty-first and no closing ]. JSON.parse on that throws, the catch block logged it and returned nothing, and because labeling was designed to fail gracefully and leave existing titles intact, the failure was invisible from the UI.

Two design changes came out of this, and both are in the final code: split the work into small batches so no single response can grow large enough to truncate, and make the parsing resilient enough that one bad batch can't take down the whole run.

Batching the Requests

Create src/pipeline/label.ts, starting with the per-batch request function:

import { getAllThreads, putThreads, getAllBrands } from "../db/index";
import type { IntentThread } from "../types";

interface ThreadDescriptor {
  id: string;
  keywords: string[];
  domains: string[];
  sampleTitles: string[];
  domainContext: string[];
}

interface LabelResult {
  id: string;
  title: string;
  summary: string;
  type: string;
  nextStep: string;
}

const VALID_TYPES: ReadonlySet = new Set([
  "buying",
  "research",
  "learning",
  "planning",
  "unclassified",
]);

const BATCH_SIZE = 10;
const MAX_TOKENS_PER_BATCH = 4000;

async function callClaudeBatch(
  apiKey: string,
  systemPrompt: string,
  batch: ThreadDescriptor[],
): Promise {
  const response = await fetch("https://api.anthropic.com/v1/messages", {
    method: "POST",
    headers: {
      "content-type": "application/json",
      "x-api-key": apiKey,
      "anthropic-version": "2023-06-01",
      "anthropic-dangerous-direct-browser-access": "true",
    },
    body: JSON.stringify({
      model: "claude-haiku-4-5-20251001",
      max_tokens: MAX_TOKENS_PER_BATCH,
      system: systemPrompt,
      messages: [
        {
          role: "user",
          content: JSON.stringify(batch),
        },
      ],
    }),
  });

  if (!response.ok) {
    let body = "";
    try { body = (await response.text()).slice(0, 400); } catch { }
    console.error(
      `[openloops] label: API request failed\n` +
      `  → HTTP \({response.status} \){response.statusText}\n` +
      `  body: ${body || "(empty)"}`,
    );
    if (response.status === 401) {
      throw new Error("Invalid API key. Check your Anthropic API key and try again.");
    }
    throw new Error(`API request failed: \({response.status} \){response.statusText}`);
  }

  const data = await response.json();
  const raw: string = data.content[0].text;

  const cleaned = raw
    .trim()
    .replace(/^```(?:json)?\s*/, "")
    .replace(/```\s*$/, "")
    .trim();

  try {
    return JSON.parse(cleaned);
  } catch (err) {
    console.error(`[openloops] label: parse error: ${err instanceof Error ? err.message : String(err)}`);
    console.error(`[openloops] label: raw tail (last 400 chars):\n${raw.slice(-400)}`);
    return null;
  }
}

BATCH_SIZE of 10 with MAX_TOKENS_PER_BATCH of 4000 is the direct answer to the truncation problem. Ten threads' worth of labels comfortably fits inside 4000 output tokens with room to spare, so a batch can't hit the ceiling and get cut off. A history with forty threads becomes four independent requests rather than one oversized one.

The request itself uses raw fetch rather than Anthropic's TypeScript SDK, because the SDK isn't built to run in a browser or extension context.

Browser-originated calls to the Anthropic API also require the anthropic-dangerous-direct-browser-access header, which is what opts into this usage pattern. The model is Claude Haiku, the fastest and cheapest in the lineup, which is well-matched to a high-volume, structured-output task like this one where you're making several calls and want them quick.

The error handling splits into two deliberately different behaviors. An HTTP-level failure (a 401 from a bad key, a 429 from rate limiting) throws, because every subsequent batch would fail the same way and there's no point continuing. A parse failure, by contrast, returns null rather than throwing, so the caller can skip just that one batch and keep going with the rest.

The fence-stripping before JSON.parse handles a common real-world wrinkle: models sometimes wrap JSON output in a Markdown code fence (```json), even when asked for raw JSON. The two .replace calls strip a leading fence and a trailing fence if present, tolerating surrounding whitespace, so a response comes through whether or not it arrived wrapped.

When parsing still fails, the catch logs the last 400 characters of the raw response, which is precisely where you'd see the truncation signature of a cut-off array, the diagnostic that would have made the original bug obvious in minutes.

Building the Prompt and Merging Results

The public labelThreads function builds the descriptors, runs the batches, and merges what comes back:

export async function labelThreads(apiKey: string): Promise<{ labeled: number }> {
  const threads = await getAllThreads();
  if (threads.length === 0) return { labeled: 0 };

  const allBrands = await getAllBrands();
  const brandMap = new Map(allBrands.map((b) => [b.domain, b]));

  const descriptors: ThreadDescriptor[] = threads.map((t) => {
    const keywords = [...new Set(t.sessions.flatMap((s) => s.keywords))].slice(0, 8);
    const domains  = [...new Set(t.sessions.flatMap((s) => s.domains))].slice(0, 5);
    const titles   = [...new Set(t.sessions.flatMap((s) => s.events.map((e) => e.title)))].slice(0, 20);

    const domainContext = domains
      .map((d) => {
        const brand = brandMap.get(d);
        if (!brand || !brand.name) return null;
        let line = `\({d}: \){brand.name}`;
        if (brand.description) line += ` — ${brand.description}`;
        if (brand.industry)    line += ` (${brand.industry})`;
        return line;
      })
      .filter((s): s is string => s !== null);

    return { id: t.id, keywords, domains, sampleTitles: titles, domainContext };
  });

  const systemPrompt = `You label browsing intent threads. Return ONLY a JSON array — no markdown fences, no explanation.
Each element: { "id": "", "title": "<3-6 word title>", "summary": "<1 sentence>", "type": "", "nextStep": "" }
The nextStep must be grounded in what the person was actually looking at. Be specific — name the actual decision, comparison, or action (e.g. "Decide between MacBook Pro and Dell XPS — your open question was battery life") rather than generic advice ("continue researching"). Use the sampleTitles and domainContext to ground it.
Each thread descriptor may include a "domainContext" array of company descriptions for the sites visited. When present, use these to produce sharper, more specific titles, summaries, and next steps grounded in what each company actually does.
Respond with exactly one array covering every thread in the request.`;

  const allResults: LabelResult[] = [];
  let failedBatches = 0;
  for (let i = 0; i < descriptors.length; i += BATCH_SIZE) {
    const batch = descriptors.slice(i, i + BATCH_SIZE);
    const results = await callClaudeBatch(apiKey, systemPrompt, batch);
    if (results === null) {
      failedBatches++;
      continue;
    }
    allResults.push(...results);
  }

  const byId = new Map(allResults.map((r) => [r.id, r]));

  let labeled = 0;
  const updated = threads.map((t) => {
    const label = byId.get(t.id);
    if (!label) return t;

    const type = VALID_TYPES.has(label.type as IntentThread["type"])
      ? (label.type as IntentThread["type"])
      : t.type;

    labeled++;
    return {
      ...t,
      title:    label.title    || t.title,
      summary:  label.summary  || undefined,
      nextStep: label.nextStep || undefined,
      type,
    };
  });

  await putThreads(updated);
  return { labeled };
}

Each thread is compressed into a ThreadDescriptor carrying only what Claude needs to label it: up to eight keywords, five domains, and twenty sample page titles, capped so a thread with hundreds of events doesn't bloat the payload.

The domainContext field is the hook for the brand-grounding step covered in the next section. It's empty for now since no brands have been fetched yet, which is exactly why labeling works fine on its own and gets sharper once grounding is added.

The merge step is where a failed batch costs you only its own threads. Results come back as a flat list across all successful batches, indexed by thread id into byId.

Then every thread is walked: if a label came back for it, the AI title, summary, next step, and type are merged in, with the returned type validated against VALID_TYPES and falling back to the heuristic type if the model returned something unexpected. If no label came back, because that thread's batch failed to parse, the thread is returned untouched, keeping the keyword title and heuristic classification it already had.

A single failed batch costs you ten threads' worth of polish, not the entire run, and never corrupts a thread with malformed data.

Notice that title, summary, and nextStep all guard against empty strings with || t.title and || undefined. A thread always has a usable title even if the model returned a blank one, and summary and nextStep stay undefined rather than becoming empty strings. This keeps the dashboard's "does this thread have a summary?" checks honest.

Checkpoint

Labeling needs a key and a button, both of which arrive with the dashboard later in this guide, so a full end-to-end test waits until then.

What you can verify now is that src/lib/settings.ts and src/pipeline/label.ts compile, and that the request shape is correct by calling labelThreads with a real key from a temporary test harness if you want immediate feedback. When it runs against built threads, the console will show batch progress, and your threads' titles in IndexedDB will change from keyword fragments to readable phrases, with summary and nextStep fields appearing for the first time.

The labels are already a large improvement, but they're working from keywords and bare domain names. This means a thread built around mastra.ai and langchain.com has no idea those are AI agent frameworks. It only sees two domain strings.

The next section closes that gap by resolving domains into real company descriptions before labeling. This is the grounding step that gives the AI something concrete to reason about.

How to Ground Labels with context.dev

This is the most distinctive idea in openloops, so it's worth stating plainly before any code: instead of asking the model to label a thread from keywords and bare domain names, openloops first resolves each domain into a real company description – what the company is, what industry it's in, what it actually does – and feeds those descriptions into the labeling prompt. The model labels the thread knowing that mastra.ai and langchain.com are both AI agent frameworks, rather than seeing two opaque strings it has to guess about.

A thread whose keywords are "mastra langchain sholajegede" produces, ungrounded, a title like "Mastra Langchain Sholajegede", a literal echo of the keywords. Grounded with the knowledge that those domains are competing agent frameworks, the same thread becomes "Benchmarking Mastra against LangChain", a title that names the actual intent.

The raw material for a good label was always there in the browsing. What was missing was the context to interpret it, and that context is exactly what a brand-intelligence API provides.

What the API Returns

openloops uses context.dev, which resolves a domain into a structured brand record: company name, a one-line description, industry classification, brand colors, and logo URLs. The grounding step needs the name, description, and industry, while the logo and colors get used later by the dashboard to render domain chips.

This step is entirely optional: the labeling from the previous section works without it, and grounding simply makes the output sharper when a context.dev key is present.

Like the Anthropic key, the context.dev key lives in chrome.storage.local, via the same getter/setter pattern in src/lib/settings.ts:

export async function getContextKey(): Promise {
  const result = await chrome.storage.local.get("contextDevApiKey");
  return (result.contextDevApiKey as string) ?? null;
}

export async function setContextKey(key: string): Promise {
  await chrome.storage.local.set({ contextDevApiKey: key });
}

Brand records also need a place to be cached, since resolving the same domain twice is wasteful and costs API credits. Bump DB_VERSION to 4 and add a domain_brands store keyed by domain:

import type { RawEvent, Session, IntentThread, Brand } from "../types";

interface OpenloopsDB extends DBSchema {
  raw_events: { key: string; value: RawEvent; indexes: { by_visitedAt: number } };
  sessions: { key: string; value: Session; indexes: { by_startedAt: number } };
  intent_threads: { key: string; value: IntentThread; indexes: { by_lastSeen: number } };
  domain_brands: {
    key: string;
    value: Brand;
  };
}

const DB_VERSION = 4;

Inside the upgrade callback, the new store is added with the same guard as the others, and domain_brands is keyed on domain rather than id because a domain is its own natural unique key:

if (!db.objectStoreNames.contains("domain_brands")) {
  db.createObjectStore("domain_brands", { keyPath: "domain" });
}

The matching helpers add one that's specific to caching, getCachedDomains. This returns the set of domains already resolved so the enrichment step can skip them:

export async function getBrand(domain: string): Promise {
  const db = await getDB();
  return db.get("domain_brands", domain);
}

export async function putBrands(brands: Brand[]): Promise {
  if (brands.length === 0) return;
  const db = await getDB();
  const tx = db.transaction("domain_brands", "readwrite");
  await Promise.all([...brands.map((b) => tx.store.put(b)), tx.done]);
}

export async function getAllBrands(): Promise {
  const db = await getDB();
  return db.getAll("domain_brands");
}

export async function getCachedDomains(): Promise> {
  const db = await getDB();
  const keys = await db.getAllKeys("domain_brands");
  return new Set(keys);
}

Fetching One Brand

Create src/pipeline/enrich.ts. The core is a function that resolves a single domain, and most of its length is there to make sure a slow or failing lookup can never hang or crash the whole step:

import { getCachedDomains, putBrands } from "../db/index";
import { isLocalHost } from "../lib/util";
import type { Brand } from "../types";

const API_BASE        = "https://api.context.dev/v1";
const LOGO_LINK_BASE  = "https://logos.context.dev";

const REQUEST_TIMEOUT_MS = 15_000;
const BATCH_SIZE     = 3;
const BATCH_DELAY_MS = 2_000;

interface FetchResult {
  brand: Brand | null;
  errorCode?: string;
}

async function fetchBrand(domain: string, contextKey: string): Promise {
  const url = `\({API_BASE}/brand/retrieve?domain=\){encodeURIComponent(domain)}`;
  const headers = { Authorization: `Bearer ${contextKey}` };

  async function attempt(): Promise {
    const ctrl = new AbortController();
    const tid  = setTimeout(() => ctrl.abort(), REQUEST_TIMEOUT_MS);
    try {
      return await fetch(url, { headers, signal: ctrl.signal });
    } finally {
      clearTimeout(tid);
    }
  }

  try {
    let res = await attempt();

    if (res.status === 408) {
      res = await attempt();
    }

    if (!res.ok) {
      let body = "";
      try { body = (await res.text()).slice(0, 400); } catch { }
      console.error(`[openloops] enrich: HTTP \({res.status} for "\){domain}" — ${body}`);
      return { brand: null, errorCode: String(res.status) };
    }

    let data: { status?: string; brand?: Record };
    try {
      data = await res.json();
    } catch (e) {
      return { brand: null, errorCode: "parse" };
    }

    if (data.status !== "ok" || !data.brand) {
      return { brand: null, errorCode: "shape" };
    }

    const b = data.brand as {
      title?:        string;
      description?:  string;
      colors?:       { hex?: string }[];
      logos?:        { url?: string }[];
      industries?:   { eic?: { industry?: string; subindustry?: string }[] };
    };

    const logoUrl =
      b.logos?.[0]?.url ||
      `\({LOGO_LINK_BASE}?domain=\){encodeURIComponent(domain)}`;

    return {
      brand: {
        domain,
        name:        b.title                          ?? domain,
        description: b.description                    ?? "",
        industry:    b.industries?.eic?.[0]?.industry ?? "",
        logoUrl,
        brandColor:  b.colors?.[0]?.hex               ?? "",
      },
    };

  } catch (err) {
    if (err instanceof Error && err.name === "AbortError") {
      return { brand: null, errorCode: "timeout" };
    }
    return { brand: null, errorCode: "network" };
  }
}

The request authenticates with a bearer token and hits a single brand/retrieve endpoint. The attempt inner function wraps each call in an AbortController with a 15-second timeout, so a stalled connection aborts itself rather than hanging the enrichment step indefinitely.

The finally clears the timer whether the request succeeds, fails, or aborts. A 408 response from context.dev means a cold cache miss on their side, which their documentation says to retry once, so a single retry handles it before giving up.

The response is unpacked defensively at every level: a non-OK status returns a FetchResult with the HTTP code, a body that won't parse returns a "parse" error, and a response whose shape isn't what's expected returns a "shape" error.

When the brand record does come through, each field falls back to a sensible default if absent, the company name falls back to the domain itself, the description and industry to empty strings, and the logo to context.dev's keyless logo CDN if the record carries no logo URL.

Every failure path returns { brand: null, errorCode } rather than throwing, which is what lets the batch driver above it treat a single domain's failure as a skip rather than a crash.

Enriching Domains in Batches

The public enrichDomains function resolves a list of domains, skipping ones already cached and respecting the API's rate limit:

export async function enrichDomains(
  contextKey: string,
  domains: string[],
): Promise<{ enriched: number; failed: number; error?: string }> {
  const unique = [...new Set(domains)].filter((d) => !isLocalHost(d));

  let cached: Set;
  try {
    cached = await getCachedDomains();
  } catch (err) {
    return { enriched: 0, failed: 0, error: "DB error" };
  }

  const toFetch = unique.filter((d) => !cached.has(d));
  if (toFetch.length === 0) return { enriched: 0, failed: 0 };

  let enriched = 0;
  let failed   = 0;
  let firstErrorCode: string | undefined;

  for (let i = 0; i < toFetch.length; i += BATCH_SIZE) {
    const batch   = toFetch.slice(i, i + BATCH_SIZE);
    const results = await Promise.all(batch.map((d) => fetchBrand(d, contextKey)));

    const brands = results.map((r) => r.brand).filter((b): b is Brand => b !== null);

    for (const r of results) {
      if (!r.brand) {
        failed += 1;
        if (!firstErrorCode) firstErrorCode = r.errorCode;
      }
    }

    if (brands.length > 0) {
      try {
        await putBrands(brands);
        enriched += brands.length;
      } catch (err) {
        failed += brands.length;
      }
    }

    if (i + BATCH_SIZE < toFetch.length) {
      await new Promise((resolve) => setTimeout(resolve, BATCH_DELAY_MS));
    }
  }

  let error: string | undefined;
  if (firstErrorCode) {
    const map: Record = {
      "401":     "401 — invalid key",
      "403":     "403 — check key permissions",
      "429":     "429 — rate limited, try again later",
      "timeout": "request timeout (15 s)",
      "network": "unreachable — check network/CORS",
    };
    error = map[firstErrorCode] ?? firstErrorCode;
  }

  return { enriched, failed, error };
}

The function opens by stripping local addresses with isLocalHost, the enrichment-boundary guard discussed in the self-referential noise section. This means that a dev server can never be sent to context.dev even if it slipped into a thread's domain list. It then removes already-cached domains via getCachedDomains, so re-running enrichment only ever fetches domains it hasn't seen. This keeps credit usage proportional to new browsing rather than total browsing.

The remaining domains are fetched three at a time, with a two-second pause between batches. This keeps the request rate well under the API's limit without making the user wait through a long serial queue.

Failures are tallied rather than thrown: a domain that fails to resolve increments failed and records its error code, but the loop carries on. The first error code encountered gets mapped to a human-readable message at the end so the UI can show something useful, such as an invalid-key or rate-limit notice.

The whole function returns counts rather than raising, which matters because the dashboard runs enrichment immediately before labeling, and a problem fetching brands should never prevent the labeling that follows it.

How Grounding Feeds Back into Labeling

Grounding connects back to labelThreads from the previous section, which already builds a domainContext array for each thread by looking up every domain in the brand cache:

const domainContext = domains
  .map((d) => {
    const brand = brandMap.get(d);
    if (!brand || !brand.name) return null;
    let line = `\({d}: \){brand.name}`;
    if (brand.description) line += ` — ${brand.description}`;
    if (brand.industry)    line += ` (${brand.industry})`;
    return line;
  })
  .filter((s): s is string => s !== null);

Before enrichment runs, the brand cache is empty, every lookup returns nothing, domainContext is an empty array, and the prompt falls back to keywords and domain names alone.

After enrichment, the same code produces lines like mastra.ai: Mastra — TypeScript framework for building AI agents (Developer Tools), and the labeling prompt's instruction to use domainContext "to produce sharper, more specific titles, summaries, and next steps" finally has something to work with.

The two steps are decoupled by design: labeling never requires grounding, but grounding measurably improves labeling. This is why the dashboard runs them in sequence as a single "enrich, then label" action.

Checkpoint

Like the labeling step, enrichment is exercised through the dashboard, so the full path waits for the dashboard section. For now, confirm that src/pipeline/enrich.ts and the updated src/db/index.ts compile, and that getDB() reports version 4 with domain_brands present in DevTools.

Once it runs against real threads with a context.dev key, the domain_brands store fills with cached records, and your thread labels should noticeably sharpen. The clearest single demonstration will be any thread built around niche or technical domains whose names don't, on their own, reveal what they are.

Every piece of the engine now exists: capture, sessions, clustering, scoring, labeling, and grounding. What's missing is the surface that drives them and shows the results.

The next section builds the dashboard, the three-column React interface with its onboarding flow and pipeline state machine, that turns this pipeline into something a person actually uses.

How to Design the Dashboard

The dashboard is a single React component tree rendered into the full-tab page you wired up at the very start when you set options_page in the manifest.

It does three jobs: it drives the pipeline (the buttons that run scanning, session-building, thread-building, and labeling), it displays the resulting intent map (threads grouped by status), and it hosts the assistant covered in the next section.

This section focuses on the structure and the one piece of genuinely interesting logic: the state machine that decides which pipeline button is live at any moment. We'll treat the styling at a summary level here, since it's mostly conventional CSS.

The Three-Column Layout

src/dashboard/App.tsx lays out three columns inside a flex shell. The left rail holds the pipeline controls, the API-key inputs, and the status filter. The center column is the main content: either the onboarding welcome screen or the intent map of threads. The right column holds overview statistics and the assistant chat.

┌──────────────┬───────────────────────────┬──────────────────┐
│  LEFT RAIL   │       MAIN COLUMN         │  RIGHT COLUMN    │
│              │                           │                  │
│  Pipeline    │  Welcome screen           │  Overview stats  │
│   · Scan     │    — or —                 │                  │
│   · Sessions │  Intent map:              │  Assistant chat  │
│   · Threads  │   ACTIVE   threads        │   · messages     │
│              │   STALLED  threads        │   · composer     │
│  Keys        │   DORMANT  threads        │   · model/effort │
│  Filter      │                           │                  │
└──────────────┴───────────────────────────┴──────────────────┘

Each thread renders as a card showing its title, type and status pills, the AI summary, the next-step row with a Resume button, a confidence bar, and a collapsible details section with domains, keywords, and signals.

The cards are grouped into ACTIVE, STALLED, and DORMANT sections, sorted by confidence within each group. The threads most worth acting on rise to the top of the most urgent group.

The styling lives in src/dashboard/app.css and is conventional: a dark theme defined through CSS custom properties (a near-black background, a single orange accent at --accent: #ff5c33, a small scale of grays for text and borders), a monospace font for labels and metadata, and a sans-serif for content.

The design choices that matter for usability are the status-based color coding (the accent for active, a muted amber for stalled, gray for dormant) and the confidence bar's width mapping directly to the thread's confidence score.

None of the CSS is load-bearing for understanding the build, so rather than reproduce it, the rest of this section focuses on the logic the styling sits on top of.

The Pipeline State Machine

The pipeline has a strict order: you can't build sessions before scanning history, and you can't build threads before building sessions. The dashboard encodes this as a small state machine, and getting it right is what makes the interface feel guided rather than confusing. Every button is either disabled (its input doesn't exist yet), highlighted as the next action to take, or done (re-runnable, but no longer the obvious next step).

type PipelineState = "disabled" | "next" | "done";

function pipelineStates(
  hasScanned: boolean,
  eventCount: number | null,
  sessionCount: number | null,
  threadCount: number | null,
): { scan: PipelineState; sessions: PipelineState; threads: PipelineState } {
  const hasEvents   = (eventCount   ?? 0) > 0;
  const hasSessions = (sessionCount ?? 0) > 0;
  const hasThreads  = (threadCount  ?? 0) > 0;

  if (!hasScanned)  return { scan: "next", sessions: "disabled", threads: "disabled" };
  if (!hasSessions) return { scan: "done", sessions: hasEvents ? "next" : "disabled", threads: "disabled" };
  if (!hasThreads)  return { scan: "done", sessions: "done", threads: "next" };
  return { scan: "done", sessions: "done", threads: "done" };
}

The function reads the presence of data at each stage and returns the state of all three buttons. Before any scan, only Scan is live, marked next, while the other two are disabled.

Once events exist but sessions don't, Scan flips to done and Sessions becomes next. Once sessions exist but threads don't, Threads becomes next. Once all three stages have produced output, everything is done, every step re-runnable but none demanding attention. The cascade walks the pipeline in order and lights up exactly one next action at a time, which is what turns a row of three buttons into a guided sequence.

The first parameter, hasScanned, is more subtle than a simple count. It's where a piece of plumbing from the very first capture section pays off.

The check can't just be "are there any events," because live capture starts populating raw_events the moment the extension is installed. There would always be events, and the onboarding would skip straight past the Scan step before the user had ever scanned.

The fix is the source field on every RawEvent, set to "backfill" or "live" back when you built capture. hasScanned comes from a dedicated query that checks specifically for backfill events:

export async function hasBackfillEvents(): Promise {
  const db = await getDB();
  let cursor = await db.transaction("raw_events", "readonly").store.openCursor();
  while (cursor) {
    if (cursor.value.source === "backfill") return true;
    cursor = await cursor.continue();
  }
  return false;
}

This walks raw_events until it finds a single event with source === "backfill", returning early the moment it does. Live-captured events alone never satisfy it, so "Scan my history" stays lit as the first step until the user actually runs a backfill, which is the correct onboarding behavior. The seemingly minor decision to tag each event with its origin, made several sections ago, is what makes this distinction possible now.

Driving the Welcome Screen from the Same Machine

A first-time user with no threads sees a centered welcome screen instead of an empty intent map. But rather than give that screen its own separate logic, the dashboard drives it from the same pipelineStates output. Whichever step is currently next determines which single call-to-action the welcome screen shows:

let welcomeStep: 1 | 2 | 3 = 1;
let welcomeCtaLabel = "Scan my history";
let welcomeCtaClick = handleScan;
if (scanState === "next") {
  welcomeStep = 1;
  welcomeCtaLabel = scanning ? "Scanning…" : "Scan my history";
  welcomeCtaClick = handleScan;
} else if (sessionsState === "next") {
  welcomeStep = 2;
  welcomeCtaLabel = buildingSessions ? "Building…" : "Build sessions";
  welcomeCtaClick = handleBuildSessions;
} else if (threadsState === "next") {
  welcomeStep = 3;
  welcomeCtaLabel = buildingThreads ? "Building…" : "Build your intent map";
  welcomeCtaClick = handleBuildThreads;
}

The welcome screen's single button always mirrors the rail's next action, so a user can move through scan, build sessions, and build threads by clicking one prominent button three times. The moment threads exist, the welcome screen is replaced by the intent map. The rail and the welcome screen never disagree about what to do next, because both read from the same source of truth.

Wiring the Handlers

The handlers themselves are thin: each runs a pipeline stage, then refreshes the component's view of the database. The action that runs grounding and labeling together is the one worth seeing, because it puts into practice the decoupling described in the previous two sections:

async function handleEnrichAndLabel() {
  setLabelError(null);
  setEnrichError(null);

  if (contextKey.trim() && contextKeySaved) {
    setEnriching(true);
    try {
      const allDomains = [...new Set(
        threads.flatMap((t) => t.sessions.flatMap((s) => s.domains))
      )];
      const result = await enrichDomains(contextKey.trim(), allDomains);
      if (result.error) setEnrichError(`context.dev: ${result.error}`);
      if (result.enriched > 0) {
        const all = await getAllBrands();
        setBrands(new Map(all.map((b) => [b.domain, b])));
      }
    } catch (err) {
      setEnrichError(`context.dev: ${err instanceof Error ? err.message : "unknown error"}`);
    } finally {
      setEnriching(false);
    }
  }

  setLabeling(true);
  try {
    await labelThreads(apiKey.trim());
    setThreads(await getAllThreads());
  } catch (err) {
    setLabelError(err instanceof Error ? err.message : "Labeling failed.");
  } finally {
    setLabeling(false);
  }
}

Enrichment runs only if a context.dev key is present, and it's wrapped so that any failure (like a network error, a bad key, or a rate limit) sets an error message but never stops execution. Labeling then runs unconditionally afterward, outside the enrichment block, so it proceeds whether enrichment succeeded, failed, or was skipped entirely for lack of a key.

That structure is the decoupling from the grounding section made concrete: grounding improves labeling when it works, and labeling degrades gracefully to keyword-and-domain context when it doesn't.

The enrichment error surfaces in amber rather than red, because it's a warning (labeling still happened) rather than a blocking failure. This is a small UI cue that matches the actual severity of what went wrong.

The Resume Button

One interaction ties the intent map back to live browsing. Each thread card has a Resume button that reopens the pages you were on, so acting on a thread is one click rather than a hunt through history:

const RESUME_SKIP_DOMAINS = new Set([
  "google.com", "youtube.com", "bing.com", "duckduckgo.com",
  "gmail.com", "mail.google.com",
]);

function resumeThread(thread: IntentThread): void {
  const seen = new Set();
  const urls: string[] = [];

  const sorted = thread.sessions
    .flatMap((s) => s.events)
    .sort((a, b) => b.visitedAt - a.visitedAt);

  for (const ev of sorted) {
    if (RESUME_SKIP_DOMAINS.has(ev.domain)) continue;
    if (seen.has(ev.url)) continue;
    seen.add(ev.url);
    urls.push(ev.url);
    if (urls.length >= 3) break;
  }

  urls.forEach((url, i) => {
    chrome.tabs.create({ url, active: i === 0 });
  });
}

Resume sorts the thread's events newest-first, skips search engines and webmail (which are waypoints rather than destinations you'd want to return to), dedupes by URL, and opens the three most recent meaningful pages. The first is the active tab and the rest are in the background. It's a small feature, but it's the thing that makes a thread feel like a place you can return to rather than a record of where you've been.

Checkpoint

With the dashboard wired up, the entire pipeline is finally usable end to end through the interface. Reload the extension, open the dashboard, and you should see the welcome screen prompting you to scan.

Click through scan, build sessions, build your intent map, and the threads should appear, grouped by status. Add an Anthropic key, optionally a context.dev key, and click "Label & enrich" to see titles and next steps sharpen. The full loop you've built across every previous section now runs from a single screen.

What remains is the conversational layer on the right: an AI assistant that can reason across all your threads at once and answer questions like "what should I close this week?" The next section builds it.

How to Build the AI Assistant

The labeling step asks Claude to describe one thread at a time. The assistant asks something harder: to reason across all of your threads together and answer open-ended questions about them, like what to close this week, what you've stalled on longest, or how to finish a particular one.

This is a chat interface, but a constrained one – grounded entirely in your own thread data, so its answers reference real threads by name rather than offering generic productivity advice.

The whole design rests on one idea: a chat assistant is only as good as the context it's given. So most of the work here is in building the right grounding context for each message, not in the chat mechanics themselves.

Grounding the Conversation

Before any message goes to Claude, the assistant assembles a system prompt describing the user's threads. It does this in one of two modes, depending on whether the user has clicked into a specific thread.

With no thread selected, it builds a compact digest of every thread. With one selected, it gives rich detail on that thread and a brief list of the others.

function buildGroundingContext(
  threads: IntentThread[],
  brands: Map,
  selectedThread: IntentThread | null,
): string {
  if (!selectedThread) {
    const digest = threads
      .map((t) => {
        const domains = [...new Set(t.sessions.flatMap((s) => s.domains))].slice(0, 5).join(", ");
        return `- \({t.title} (\){t.status}, \({t.type}): \){t.summary ?? "no summary yet"} | next: \({t.nextStep ?? "none"} | domains: \){domains || "none"}`;
      })
      .join("\n");

    return `\({SYSTEM_INSTRUCTION}\n\nHere is a digest of all the user's open intent threads:\n\){digest || "(no threads yet)"}`;
  }

  const keywords = [...new Set(selectedThread.sessions.flatMap((s) => s.keywords))].slice(0, 10).join(", ");
  const domains = [...new Set(selectedThread.sessions.flatMap((s) => s.domains))].slice(0, 5);

  const domainLines = domains
    .map((d) => {
      const brand = brands.get(d);
      if (brand?.description) return `- \({d}: \){brand.name} — ${brand.description}`;
      return `- ${d}`;
    })
    .join("\n");

  const sampleTitles = [...new Set(selectedThread.sessions.flatMap((s) => s.events.map((e) => e.title)))]
    .slice(0, 20)
    .map((t) => `- ${t}`)
    .join("\n");

  const otherTitles = threads
    .filter((t) => t.id !== selectedThread.id)
    .map((t) => t.title)
    .join(", ");

  return `${SYSTEM_INSTRUCTION}

The user is focused on this thread:
Title: ${selectedThread.title}
Status: ${selectedThread.status}
Type: ${selectedThread.type}
Summary: ${selectedThread.summary ?? "none"}
Next step: ${selectedThread.nextStep ?? "none"}
Keywords: ${keywords || "none"}

Domains visited:
${domainLines || "(none)"}

Recent page titles:
${sampleTitles || "(none)"}

For context, the user's other open threads are: ${otherTitles || "none"}.`;
}

The two modes match the two kinds of questions people ask. A question like "what should I close this week?" is about the whole set, so the digest mode gives Claude a one-line summary of every thread. This is enough breadth to compare and prioritize across all of them.

A question like "how do I finish this one?", on the other hand, is about a single thread, so the focused mode trades breadth for depth. It hands over that thread's keywords, its domains with their brand descriptions, and up to twenty real page titles, while still naming the other threads so Claude knows what else is in play.

The focused mode is where brand grounding shows up again. The same brand records fetched during enrichment get woven into the domain list, so when the user asks about a thread, Claude sees mastra.ai: Mastra — TypeScript framework for building AI agents rather than a bare domain. This is the identical grounding principle from labeling, now applied to conversation.

The system instruction that prefixes both modes pins the assistant to its data:

const SYSTEM_INSTRUCTION =
  `You are the assistant inside "openloops", a browser extension that reconstructs ` +
  `the user's browsing history into "intent threads" — decisions, research, or ` +
  `plans they started and haven't closed. Help the user understand and act on ` +
  `these open loops. Be concrete: reference the actual threads by name and ` +
  `suggest real next actions. You are grounded only in the thread data provided ` +
  `below — if the user asks about something not present in it, say so plainly ` +
  `rather than guessing.`;

The final instruction is the important one: telling the model to admit when something isn't in its data, rather than inventing a plausible answer, is what keeps the assistant trustworthy when a user asks about a thread that doesn't exist or a detail the data doesn't contain.

Sending a Message

The send function rebuilds the grounding context fresh on every message. The assistant always reflects the current state of the threads (including any that changed since the conversation started) and posts the whole message history to Claude:

async function send(text: string) {
  const trimmed = text.trim();
  if (!trimmed || sending) return;

  if (!keySaved) {
    setError("Add your Anthropic key above to chat.");
    return;
  }

  setError(null);
  const nextMessages: Message[] = [...messages, { role: "user", content: trimmed }];
  setMessages(nextMessages);
  setInput("");
  setSending(true);

  try {
    const systemPrompt = buildGroundingContext(threads, brands, selectedThread);
    const maxTokens = EFFORT_OPTIONS.find((e) => e.id === effort)?.maxTokens ?? 1024;

    const response = await fetch("https://api.anthropic.com/v1/messages", {
      method: "POST",
      headers: {
        "content-type": "application/json",
        "x-api-key": apiKey,
        "anthropic-version": "2023-06-01",
        "anthropic-dangerous-direct-browser-access": "true",
      },
      body: JSON.stringify({
        model,
        max_tokens: maxTokens,
        system: systemPrompt,
        messages: nextMessages.map((m) => ({ role: m.role, content: m.content })),
      }),
    });

    if (!response.ok) {
      if (response.status === 401) {
        throw new Error("Invalid API key. Check your Anthropic API key and try again.");
      }
      throw new Error(`API request failed: \({response.status} \){response.statusText}`);
    }

    const data: { content: AnthropicContentBlock[] } = await response.json();
    const reply = data.content
      .filter((b) => b.type === "text" && b.text)
      .map((b) => b.text)
      .join("");

    setMessages((prev) => [...prev, { role: "assistant", content: reply || "(empty response)" }]);
  } catch (err) {
    setError(err instanceof Error ? err.message : "Something went wrong.");
  } finally {
    setSending(false);
  }
}

The mechanics mirror the labeling request, the same endpoint, the same browser-access header, and the same 401-aware error handling, since both talk to the same API from the same constrained environment. The user's message gets appended to the running messages array, the full array is sent so the model has the conversation so far, and the assembled grounding context rides along as the system prompt. The reply is extracted by concatenating the text blocks from the response, with a fallback string if the model returned nothing usable.

Rebuilding buildGroundingContext on every send rather than once per conversation is a deliberate choice: if the user re-runs the pipeline or labels their threads mid-conversation, the next message reflects the updated data automatically, with no stale snapshot from when the chat began.

Model and Effort Controls

The assistant exposes two selectors: which model to use and how much depth to allow. Both are persisted to chrome.storage.local through the same settings pattern as the keys:

const MODEL_OPTIONS = [
  { id: "claude-haiku-4-5-20251001", label: "Haiku 4.5 — fastest" },
  { id: "claude-sonnet-4-6",          label: "Sonnet 4.6 — balanced" },
  { id: "claude-opus-4-8",            label: "Opus 4.8 — most capable" },
];

const EFFORT_OPTIONS = [
  { id: "low",    label: "Low",    maxTokens: 512 },
  { id: "medium", label: "Medium", maxTokens: 1024 },
  { id: "high",   label: "High",   maxTokens: 2048 },
];

The model selector spans the speed-versus-capability range: Haiku for quick answers, Opus for harder reasoning over a tangled set of threads. The effort selector maps to max_tokens, controlling how long an answer the model may produce. This is a reasonable proxy for response depth given the Messages API has no dedicated depth control. A user wanting a one-line answer picks Low, while one wanting a reasoned, prioritized plan picks High.

Rendering Replies and the Empty State

The assistant renders Claude's replies as Markdown, since the model naturally formats prioritized lists and step-by-step suggestions with headings and bullets. This would look like raw asterisks and hashes if rendered as plain text. Using react-markdown, the reply component is essentially {m.content} for assistant messages, with user messages rendered as plain text. The accompanying styles target the rendered Markdown elements to match the dashboard's type scale.

Before any conversation starts, the panel shows an empty state with a one-line explanation and a few suggested prompts as clickable chips, "What should I close this week?", "Summarize my open loops", "What have I stalled on longest?". These both demonstrate what the assistant can do and give a one-click way to start.

The suggested prompts shift slightly when a thread is focused, offering "How do I finish this one?" in place of the whole-set summary, matching the focused grounding mode.

A privacy line sits permanently below the composer, stating that chats send thread titles and summaries to Anthropic and nothing else leaves the device. This is the same honest disclosure principle applied throughout, placed where the user will see it before they type.

Checkpoint

With the assistant in place, openloops is feature-complete. Reload, build your intent map, add your Anthropic key, and try the suggested prompts. Ask what to close this week and the assistant should name specific threads and reason about which are easy wins versus which need a real decision. Click into a single thread and ask how to finish it, and the answer should narrow to that thread's specifics.

The conversation reflects your real, current threads, and nothing about it leaves your machine except the thread summaries you can see in the grounding context itself.

The build is done. The final section steps back to look at what you've made: how it compares to the one mainstream attempt at this idea, what the privacy model adds up to, and where you might take it next.

What You've Built, and Where to Take It

You've built a complete system: browsing history flows in through capture, gets cleaned and segmented into sessions, clustered and scored into intent threads, optionally labeled and grounded by AI, and surfaced through a dashboard with a conversational assistant. Every stage runs on your own machine, and the AI layers are optional additions on top of a pipeline that works without them.

If the clustering reminds you of Chrome's old Journeys feature, that's a fair connection. Grouping history by topic instead of by time is the same starting point.

openloops takes it further: every thread carries a confidence score and a status, the AI layer adds labels and a concrete next step, the assistant reasons across threads on demand, and the whole thing is open source and local-first. This means that you can read and change exactly what it does with your data.

What the Privacy Model Adds Up To

Privacy shaped the build at every step, and it's worth collecting what that amounted to in one place. The entire core pipeline, capture through scored threads, runs locally in IndexedDB with no network calls of any kind. Your browsing history – the raw events, the sessions, the threads – never leaves your machine for the parts of the system that work without a key.

The two AI layers are the only paths by which any data leaves the device, and both are opt-in, gated on you providing your own API key. When they run, what they send is deliberately minimal: brand enrichment sends only bare domain names to context.dev, never URLs or page contents, and stripped of any local addresses first. Labeling and the assistant send thread titles, summaries, keywords, and sample page titles to Anthropic, the grounding context you can read directly in the code, and nothing more. Keys themselves live in chrome.storage.local, which never syncs.

Where to Take it Next

The build leaves a few deliberate simplifications that make good exercises.

The most satisfying one builds directly on code you've already written. The domain side has ambient.ts, which drops domains that appear on most of your active days. But the keyword side has no equivalent, so a word that's ubiquitous for you (say typescript, if you're a TypeScript developer) survives in every session's keywords and can nudge unrelated threads together.

The fix is a frequency-based keyword detector that mirrors detectAmbientDomains almost line for line, counting days-per-keyword instead of days-per-domain:

export function detectAmbientKeywords(sessions: Session[]): Set {
  const allEvents = sessions.flatMap((s) => s.events);
  const activeDays = new Set(allEvents.map((e) => new Date(e.visitedAt).toDateString()));
  const totalActiveDays = activeDays.size;
  if (totalActiveDays < MIN_ACTIVE_DAYS) return new Set();

  const keywordDayMap = new Map>();
  for (const session of sessions) {
    const day = new Date(session.startedAt).toDateString();
    for (const kw of session.keywords) {
      if (!keywordDayMap.has(kw)) keywordDayMap.set(kw, new Set());
      keywordDayMap.get(kw)!.add(day);
    }
  }

  const ambient = new Set();
  for (const [kw, days] of keywordDayMap) {
    if (days.size / totalActiveDays >= UBIQUITY_THRESHOLD) ambient.add(kw);
  }
  return ambient;
}

You'd then strip these keywords inside similarity exactly as ambient domains are stripped today, filtering them out of both sessionKeywords and the thread's keywordSet before the Jaccard call.

Two smaller exercises round it out. The session gap, similarity threshold, and ambient ubiquity threshold are all hardcoded constants. Lifting them into a settings panel backed by chrome.storage.local (the same store the API keys already use) would let you tune clustering to your own browsing.

And extractDomain strips only a leading www., so news.bbc.co.uk and bbc.co.uk are treated as different domains. Swapping its hostname logic for a library that uses the Public Suffix List (the canonical list of domain suffixes like .co.uk that browsers use to know where a registrable domain actually ends) would collapse subdomains of the same site correctly.

Since the whole pipeline is local and inspectable, each of these is straightforward to try against your own real data and see the effect immediately.

Wrapping up

openloops turns the flat, chronological record your browser keeps into a map of what you were actually trying to do, and helps you close the loops you left open.

The engineering underneath – time-gap segmentation, weighted Jaccard clustering with ambient-domain correction, heuristic scoring, AI labeling grounded in real company data, and a conversational layer over the result – is the kind of layered system where each stage is simple on its own and the value comes from how they compose.

Resources

Source Code

The complete source is available on GitHub under the MIT license, so you can run it, read it, and reshape it to fit how you browse. If it helped you, consider giving it a star.

Core Documentation

Chrome Extensions: Manifest V3: the extension platform openloops is built on
chrome.history API: the search and getVisits methods the backfill relies on
chrome.tabs API: onUpdated for live capture and create for Resume
chrome.storage API: where API keys and preferences live, locally
Anthropic API reference: the Messages endpoint used for labeling and the assistant

Services used

Anthropic Console: create the API key for AI labeling and the assistant
context.dev documentation: the brand-intelligence API used for grounding
IndexedDB (MDN): the local database every pipeline stage reads and writes

Build tooling

Vite: the build tool and dev server
CRXJS Vite plugin: compiles a Manifest V3 extension with hot reloading
idb: the typed, promise-based IndexedDB wrapper
react-markdown: renders the assistant's Markdown replies

Debugging tools

Chrome extension service worker DevTools: inspect live-capture logs and the pipeline console.table output
The Application → IndexedDB panel in Chrome DevTools: browse raw_events, sessions, intent_threads, and domain_brands directly to verify each stage

Mastra vs LangChain: Building an AI Agent Pipeline and Analyzing the Data

Shola Jegede — Sat, 13 Jun 2026 07:17:36 +0000

A week ago, I saw this tweet:

I had just shipped SupportMesh, a multi-tenant AI support platform built on Mastra, so I had opinions from production.

I liked the .dowhile() loop, the typed step schemas, and the way createWorkflow kept orchestration logic in one place. What I didn't like was the token overhead: every agent step initialises Mastra's tool loop manager regardless of whether tools are needed, and across a four-step pipeline that adds up to seconds of extra latency and thousands of extra tokens per run.

At the same time, I was looking at LangChain for a separate project I was starting. The approach is completely different from Mastra. Instead of a workflow with typed step contracts, you build a directed graph where nodes are plain async functions and state is a single shared object.

The promise is leaner execution and more explicit control over exactly what goes into each model call, which, given the token overhead I had been seeing with Mastra, was exactly the kind of thing I wanted to understand properly.

So rather than picking one based on documentation and vibes, I built the same pipeline in both and measured everything. The same five-step research and synthesis pipeline, twice, with every piece instrumented: tokens per step, latency per step, the exact prompt sent to Claude at each stage, the raw Tavily search results, and a production-grade evaluation system that actually produces varied scores rather than giving everything a 7.

Then I built a real-time web dashboard on Convex and Next.js so you can run any topic yourself and see every decision both frameworks make to get there.

Prerequisites
The Tools We're Using
Why This Pipeline
The Project Structure
Building the Mastra Pipeline
Building the LangChain Pipeline
The Critic That Gave Everything a 7 out of 10
- What Production-Grade Evaluation Actually Looks Like
- Extracting JSON from Chain-of-Thought Output
The Evaluation Bias I Almost Shipped
The Real-Time Dashboard
What the Data Actually Shows
Try it Yourself

Prerequisites

To follow along and run this yourself, you'll need four things:

Node.js 22 or later: the pipeline packages use modern TypeScript features that require a recent Node version.
An Anthropic API key: you can get one at console.anthropic.com. Claude Haiku 4.5 is cheap enough that running this benchmark a dozen times costs a few cents.
A Tavily API key: you can get one at tavily.com. The free tier gives you 1,000 searches a month, which is more than enough to run this benchmark repeatedly.
A Convex account: you can sign up at convex.dev. The free tier covers everything here.

Once you have those, the setup section at the end of this article walks through exactly where each one goes.

The Tools We're Using

Before getting into the build, it helps to know what each tool I used is and why it's in the stack. If you're already familiar with all of these, you can skip ahead.

Mastra is a TypeScript-first framework for building AI-powered applications and agents. The idea is that you define individual steps with typed input and output schemas, chain them into a workflow, and the framework handles the data flow between them. It has opinions about structure, which is either a feature or a constraint depending on what you're building.

LangChain is one of the most widely used frameworks for building LLM applications. It started in Python and has a TypeScript version.

For agent orchestration specifically, the relevant piece is LangGraph, which is LangChain's graph-based execution layer. Instead of a workflow with typed step contracts, you build a directed graph: nodes are plain async functions, state is a single shared object that every node reads from and writes to, and the flow between nodes is controlled by edges.

Claude Haiku 4.5 is the model powering all agents. It is Anthropic's fastest and most cost-efficient model, which makes it the right choice here.

Tavily is a web search API built specifically for AI agents. Unlike a general search API, it returns structured results with relevance scores and content snippets that are ready to pass directly into a model prompt. The free tier is generous enough to run this benchmark without paying anything.

I used it here because it has a clean TypeScript SDK, it works in both Mastra tools and plain LangChain nodes without any adapter layer, and the search results are consistent enough that both pipelines are working with the same quality of input.

Convex is a real-time database with a React hook, useQuery, that automatically re-renders your component whenever the underlying data changes. No polling, no WebSocket setup, and no manual state syncing. When both pipelines are writing step data as they execute, the run page just updates.

Next.js is the web framework for the dashboard. App Router, API routes for the pipeline execution, and server components where they make sense.

Why This Pipeline

A simple comparison wouldn't tell me anything useful, because the difference between frameworks only shows up when you actually push them.

The pipeline I landed on has five steps:

Topic
  ↓
1. RESEARCH   (Tavily web search, 5 results with relevance scores)
2. ANALYSIS   (Extract 5 key findings, 3 themes, 1 central argument)
3. WRITE      (Draft a structured ~400-word report)
4. CRITIC     (Score the draft, provide dimension-level feedback)
5. LOOP       (Revise if score below 7, output if passes or 3 iterations used)

I chose each step because it stresses the frameworks differently.

The research step requires a real tool call, which is where Mastra's Agent abstraction does its heaviest work. The analysis step needs structured JSON output, which tests how each framework enforces output shape. The write step has strict content requirements enforced purely through prompt engineering. The critic needs to do chain-of-thought reasoning and produce structured JSON at the same time, which turns out to be harder than it sounds. And the revision loop tests perhaps the most fundamental difference between the two frameworks: how each one expresses conditional iteration.

Taken together, this covers most of what you would actually build with an agent framework in production: tool calls, structured output, multi-step orchestration, quality evaluation, and feedback loops.

The Project Structure

Everything lives in a single monorepo using npm workspaces, which means all packages share a single node_modules at the root and can import each other directly:

mastra-vs-langchain/
├── packages/
│   ├── mastra-pipeline/          # Mastra implementation
│   ├── langchain-pipeline/       # LangChain/LangGraph implementation
│   ├── web/                      # Next.js 16 App Router dashboard
│   └── shared/                   # Shared TypeScript types
├── convex/                       # Real-time backend
└── package.json                  # Workspace root

The most important piece of the shared package is the PipelineCallbacks interface, which both pipeline implementations must satisfy. This is the contract that lets the dashboard receive live events from either framework: step starts, step completions, token counts, and Tavily results, all without knowing anything about Mastra or LangChain specifically:

// packages/shared/src/types.ts
export interface PipelineCallbacks {
  onPipelineStart: () => Promise;
  onPipelineComplete: (id: string, data: PipelineCompleteData) => Promise;
  onPipelineError: (id: string, error: string) => Promise;
  step: {
    onStepStart: (stepName: string, iteration: number, input: string) => Promise;
    onStepComplete: (stepId: string, data: StepCompleteData) => Promise;
    onStepError: (stepId: string, error: string) => Promise;
  };
}

Every Convex write, live log entry, and token count flows through this interface. Adding a new framework to the benchmark in the future means implementing this interface and plugging it into the API route, and nothing else needs to change.

Building the Mastra Pipeline

If you haven't used Mastra before, the core mental model is this: you define individual steps with typed input and output schemas, chain them together into a workflow, and Mastra manages the data flow between them.

The framework is opinionated about structure but that structure gives you type safety across the entire pipeline and makes the orchestration logic easy to read.

The Search Tool

Mastra tools are created with createTool, which takes a Zod input schema and an execute function that receives the validated input directly:

// packages/mastra-pipeline/src/tools/search.ts
import { createTool } from "@mastra/core/tools";
import { z } from "zod";
import { tavily } from "@tavily/core";

const client = tavily({ apiKey: process.env.TAVILY_API_KEY! });

export let lastTavilyCapture: { query: string; results: any[] } = {
  query: "",
  results: [],
};

export function resetTavilyCapture() {
  lastTavilyCapture = { query: "", results: [] };
}

export const searchTool = createTool({
  id: "web-search",
  description: "Search the web for information on a topic",
  inputSchema: z.object({ query: z.string() }),
  execute: async ({ query }) => {
    lastTavilyCapture = { query, results: [] };
    const results = await client.search(query, {
      maxResults: 5,
      searchDepth: "basic",
    });
    lastTavilyCapture.results = results.results;
    return { results: results.results };
  },
});

The lastTavilyCapture module-level variable is a deliberate workaround for a real constraint. Mastra's tool execution happens inside the agent's internal tool loop, which sits one layer below the workflow step.

I needed to capture the Tavily query and results for the dashboard so users can see the actual URLs and relevance scores for each run, but threading a callback through the agent's tool execution context would have required patching Mastra internals. Capturing at module scope and calling resetTavilyCapture() at the start of each research step is less elegant but completely reliable, and it prevents stale data from a previous run bleeding into the current one.

The Agents

Each step in the Mastra pipeline runs as a separate Agent instance. One thing worth knowing if you're just getting started with Mastra is that it requires an explicit id field alongside name. If you skip it, TypeScript throws a confusing error about missing required fields that doesn't point at the actual problem:

// packages/mastra-pipeline/src/agents/researcher.ts
export const researcherAgent = new Agent({
  name: "Researcher",
  id: "researcher",           // required in v1.41 - easy to miss
  instructions: `You are a research agent. When given a topic, use the 
  web-search tool to find 5 relevant results. Return ALL the raw search 
  results including titles, URLs, and content snippets as a formatted string.`,
  model: anthropic("claude-haiku-4-5"),
  tools: { searchTool },
});

The writer agent carries all its content requirements directly in the instructions rather than in a separate validation layer. This keeps the constraints in one visible place, which matters when the critic is giving feedback about which specific requirements the draft violated:

// packages/mastra-pipeline/src/agents/writer.ts
export const writerAgent = new Agent({
  name: "Writer",
  id: "writer",
  instructions: `You are a research analyst writing for a technical audience.

STRICT REQUIREMENTS:
- Opening sentence must state a specific finding from the research.
  Never open with "X is increasingly important."
- Every paragraph makes exactly one argument. State it first.
  Support it with specific evidence.
- Name specific tools, frameworks, companies, numbers, and dates.
- Conclusion must make a specific recommendation or prediction.
  It must not restate the introduction.
- Target length: 350-450 words.

FORBIDDEN PHRASES:
"it is important to note", "it is worth noting",
"organizations must consider", "in conclusion", "in summary",
"as we look to the future", "rapidly evolving landscape",
any sentence equally true if you replaced the topic`,
  model: anthropic("claude-haiku-4-5"),
});

The writeCriticStep: Why Write and Critic Live in the Same Step

While implementing Mastra, I made one architectural decision here that diverges from most tutorials, and it's worth understanding why.

Mastra's .dowhile() construct loops a single step until a condition is met. That's clean when you have one thing to repeat, but the revision loop needs two things: a write step followed by a critic step. You can either combine them into one step, or build a nested workflow where the inner workflow contains both steps.

A nested workflow adds a layer of complexity that doesn't buy you anything in this case, so the write and critic phases live together in writeCriticStep. The step runs the writer first, then immediately runs the critic on the draft, and returns a combined output that includes both the draft and the score:

const writeCriticStep = createStep({
  id: "write-critic",
  inputSchema: z.object({
    topic: z.string(),
    research: z.string(),
    analysis: z.string(),
    keyFindings: z.array(z.string()),
    mainThemes: z.array(z.string()),
    centralArgument: z.string(),
    draft: z.string().optional(),       // populated after first iteration
    score: z.number().optional(),       // populated after first iteration
    feedback: z.string().optional(),    // populated after first iteration
    iterations: z.number().optional(),
  }),
  outputSchema: z.object({
    // ... all input fields plus draft, score, feedback, iterations
  }),
  execute: async ({ inputData }) => {
    const iteration = (inputData.iterations ?? 0) + 1;

    // WRITE phase
    let writerPrompt = `Topic: "\({inputData.topic}"\n\nResearch:\n\){inputData.research}\n\nAnalysis:\n${inputData.analysis}`;
    if (inputData.feedback && inputData.draft) {
      // On revisions, the writer sees its previous attempt and the specific feedback
      writerPrompt += `\n\nPrevious draft:\n\({inputData.draft}\n\nFeedback:\n\){inputData.feedback}`;
    }

    const writeStepId = await callbacks.step.onStepStart("write", iteration, writerPrompt.slice(0, 500));
    const writerResult = await writerAgent.generate(writerPrompt);
    const draft = writerResult.text;
    await callbacks.step.onStepComplete(writeStepId, { output: draft, /* token data */ });

    // CRITIC phase: runs immediately after write, on the same draft
    const criticPrompt = `RESEARCH:\n\({inputData.research}\n\nANALYSIS:\n\){inputData.analysis}\n\nDRAFT:\n${draft}`;
    const criticStepId = await callbacks.step.onStepStart("critic", iteration, draft.slice(0, 500));
    const criticResult = await criticAgent.generate(criticPrompt);
    const parsed = extractJson(criticResult.text);
    const score = parsed?.score ?? 4;
    const feedback = parsed?.feedback ?? "Score parsing failed";
    await callbacks.step.onStepComplete(criticStepId, { output: criticResult.text, criticScore: score });

    return { ...inputData, draft, score, feedback, iterations: iteration };
  },
});

The .dowhile() condition then checks whether to loop again. It receives the output of the previous writeCriticStep as inputData, so it can read the score directly:

const workflow = createWorkflow({
  id: `research-pipeline-${Date.now()}`,  // timestamp prevents conflicts on concurrent runs
  inputSchema: z.object({ topic: z.string() }),
})
  .then(researchStep)
  .then(analysisStep)
  .dowhile(
    writeCriticStep,
    async ({ inputData }) => inputData.score < 7 && inputData.iterations < 3
  )
  .commit();

The Date.now() in the workflow ID is there because Mastra workflows with a static ID conflict when two runs start concurrently. Adding the timestamp gives each run a unique workflow instance.

Token Capture

After any agent.generate() call, usage data lives on the result object. The shape changes between Mastra versions, so checking both possible field names is the safe approach:

const inputTokens =
  (result as any).usage?.promptTokens ??
  (result as any).usage?.inputTokens ??
  0;
const outputTokens =
  (result as any).usage?.completionTokens ??
  (result as any).usage?.outputTokens ??
  0;

Building the LangChain Pipeline

LangChain/LangGraph solves the same problem with a fundamentally different mental model.

Where Mastra gives you a workflow with explicitly typed step contracts, LangGraph gives you a directed graph. Nodes are plain async functions, state is a single shared mutable object that flows through the graph, and the execution order is determined by edges rather than a chain of .then() calls.

The State Annotation

Before writing any nodes, you define the shape of the shared state using Annotation.Root. Every node in the graph reads from and writes to this object:

// packages/langchain-pipeline/src/graph/state.ts
export const PipelineState = Annotation.Root({
  topic: Annotation(),
  research: Annotation(),
  analysis: Annotation(),
  draft: Annotation(),
  score: Annotation(),
  feedback: Annotation(),
  iterations: Annotation(),
  finalReport: Annotation(),
  criticDimensions: Annotation(),
});

Coming from Mastra, the difference in how data flows is significant. In Mastra, each step declares what it receives and returns, and the framework enforces that contract at the TypeScript level.

In LangGraph, any node can read or write any field in the shared state. The structure comes from the graph topology rather than the type system, which means Mastra catches data flow bugs at compile time while LangGraph makes it easier to add new fields to the pipeline without touching every step's schema.

The Factory Pattern

LangGraph nodes are plain async functions, which is exactly what makes them lean: no framework overhead, no initialization, just your code calling the model.

The challenge is that I needed to thread callbacks and a shared token accumulator through all four nodes, and plain functions have no built-in mechanism for that.

The solution is a factory function that creates all four nodes as closures over the shared state:

// packages/langchain-pipeline/src/graph/nodes.ts
export function createNodes(
  callbacks: PipelineCallbacks,
  acc: { inputTokens: number; outputTokens: number }
) {
  const tavilyClient = tavily({ apiKey: process.env.TAVILY_API_KEY! });

  async function researchNode(state: PipelineStateType): Promise> {
    const stepId = await callbacks.step.onStepStart("research", 1, state.topic);
    const results = await tavilyClient.search(state.topic, { maxResults: 5, searchDepth: "basic" });
    const research = results.results
      .map((r, i) => `[\({i + 1}] \){r.title}\nURL: \({r.url}\nContent: \){r.content}`)
      .join("\n\n");
    await callbacks.step.onStepComplete(stepId, {
      output: research,
      promptSent: state.topic,
      timeMs: elapsed,
      inputTokens: 0,      // research step uses Tavily, not an LLM
      outputTokens: 0,
      model: "tavily-search",
      tavilyQuery: state.topic,
      tavilyResults: JSON.stringify(results.results),
    });
    return { research };
  }

  // analysisNode, writeNode, criticNode follow the same pattern

  return { researchNode, analysisNode, writeNode, criticNode };
}

Notice the research node returns 0 tokens because it calls Tavily directly without any LLM involvement, which is one of the key differences that shows up in the benchmark data. Each subsequent node accumulates tokens directly into the shared acc object:

const inputTokens = response.usage_metadata?.input_tokens ?? 0;
const outputTokens = response.usage_metadata?.output_tokens ?? 0;
acc.inputTokens += inputTokens;
acc.outputTokens += outputTokens;

LangChain's ChatAnthropic puts usage on response.usage_metadata, which is cleanly typed and requires no casting.

The Graph and the Node Naming Collision

One thing LangGraph enforces that's easy to miss: node names can't conflict with state annotation keys. Naming a node "research" throws a runtime error because state.research already exists as a state channel, and the error message doesn't explain why. Renaming to "researcher" and "analyzer" fixes it:

export const pipeline = new StateGraph(PipelineState)
  .addNode("researcher", researchNode)   // NOT "research": conflicts with state.research
  .addNode("analyzer", analysisNode)     // NOT "analysis": conflicts with state.analysis
  .addNode("write", writeNode)
  .addNode("critic", criticNode)
  .addEdge(START, "researcher")
  .addEdge("researcher", "analyzer")
  .addEdge("analyzer", "write")
  .addEdge("write", "critic")
  .addConditionalEdges("critic", shouldRevise, {
    revise: "write",
    end: END,
  })
  .compile();

The revision loop in LangGraph is expressed as a conditional edge with a routing function:

function shouldRevise(state: PipelineStateType): string {
  if (state.score >= 7 || state.iterations >= 3) return "end";
  return "revise";
}

After every critic execution, shouldRevise runs and returns either "revise" to loop back to the write node or "end" to exit the graph. That's the state machine equivalent of Mastra's .dowhile(): the same conditional logic expressed as graph routing rather than as a named loop construct.

The Retry Wrapper

Both frameworks hit intermittent TLS session reuse errors when making concurrent HTTPS requests. The error look like this: SSL routines:tls_get_more_records:decryption failed or bad record mac. A retry wrapper with linear backoff handles it:

async function retryOnFetch(fn: () => Promise, retries = 3): Promise {
  for (let i = 0; i <= retries; i++) {
    try {
      return await fn();
    } catch (e: any) {
      const shouldRetry =
        e?.message?.includes("fetch") ||
        e?.message === "fetch failed" ||
        e?.message?.includes("SSL") ||
        e?.message?.includes("ECONNRESET") ||
        e?.message?.includes("other side closed") ||
        e?.cause?.code === "ECONNRESET";
      if (i < retries && shouldRetry) {
        await new Promise((r) => setTimeout(r, 1000 * (i + 1)));
        continue;
      }
      throw e;
    }
  }
  throw new Error("unreachable");
}

Every llm.invoke() call in the LangChain nodes is wrapped in this. In the web app's API route, there's an equivalent retryMutation wrapper around every Convex call for the same reason.

The Critic That Gave Everything a 7 out of 10

With both pipelines running, I tested a few topics. Every score came back 7 out of 10, regardless of topic, framework, or iteration.

This is actually a well-documented failure mode called LLM-as-judge bias. When you ask a language model to assign a score from 1 to 10 without giving it structured criteria and explicit anchors for each score level, it gravitates toward 7. It's the socially safe answer: high enough to signal quality, low enough to seem fair, and it requires no real justification. The model has no incentive to discriminate because nothing in the prompt forces it to.

My original critic was this:

You are a critical editor. Score the draft 1-10 on accuracy,
clarity, and depth. Return { score, feedback }.

That single sentence was the entire prompt, so obviously it gave everything a 7.

What Production-Grade Evaluation Actually Looks Like

The solution I used comes from the G-Eval paper, which is also the approach behind tools like DeepEval and RAGAS. The key insight is that you need three things working together: the judge must reason step-by-step before assigning any score, the dimensions being scored must be independent of each other, and each score level must have an explicit description of what it means, not just "1 is bad, 10 is perfect."

So, I rebuilt the critic around six mandatory steps that must all complete before a number is produced:

Claim audit: every factual claim in the report gets classified as GROUNDED (supported by a specific search result), INFERRED (reasonable extension of the research), UNSUPPORTED (no basis in the results), or HALLUCINATED (contradicts the results).
Specificity audit: every generic sentence and every forbidden phrase gets flagged explicitly.
Insight audit: checks whether the conclusion actually adds something beyond restating the introduction.
Counterfactual check: the judge must name at least one specific belief a reader would hold after reading this that they wouldn't hold from just the topic title alone. If it can't identify one, the insight score can't exceed 6.
Dimension scoring: three independent scores with explicit anchors for each level.
Floor rule: if any single dimension scores 4 or below, the final score can't exceed 6 regardless of the other dimensions.

The floor rule deserves a specific explanation because it addresses a real failure mode: without it, a report that hallucinates facts could score 2 on source fidelity but still end up with a passing score on the weighted average if specificity and insight are high enough. A critical failure in one dimension should disqualify the report, not get diluted.

This is the full critic prompt, which is shared between Mastra and LangChain via a constant in nodes.ts:

const CRITIC_INSTRUCTIONS = `You are a senior research editor.
Catch the specific ways AI-generated reports fail.

STEP 1: CLAIM AUDIT
Classify every claim: [GROUNDED] [INFERRED] [UNSUPPORTED] [HALLUCINATED]

STEP 2: SPECIFICITY AUDIT
List sentences that are generic, use forbidden phrases, or make no
falsifiable claims. Forbidden phrases: "it is important to note",
"organizations must consider", "rapidly evolving", "as we look to the future"

STEP 3: INSIGHT AUDIT
Does the conclusion add anything not already in the introduction?

STEP 3.5: COUNTERFACTUAL CHECK
Name one specific belief a reader holds after reading this that they
would not hold from just the topic title. If you cannot identify one,
insight cannot exceed 6.

STEP 4: SCORE EACH DIMENSION

SOURCE FIDELITY (40% weight):
5-6: Claims accurate but traced to general topic knowledge, not these specific results
7:   Most claims traceable, at least one source cited by name
8:   All major claims grounded, two or more named sources with specific details
9-10: Every claim traces to a named source, at least one statistic used

SPECIFICITY (30% weight):
5-6: Some specific claims but generic analysis between paragraphs
7:   Mostly specific, minor filler remains
8:   Every paragraph falsifiable, named entities throughout
9-10: Zero sentences survive if you swap the topic

INSIGHT (30% weight):
5-6: Some synthesis but conclusion could have been written before reading
7:   Conclusion makes a recommendation that follows from the evidence
8:   Identifies a tradeoff the reader has not considered
9-10: A senior engineer would reconsider an architectural decision after reading this

STEP 5: FLOOR RULE
If any dimension scores 4 or below, the final score cannot exceed 6.

STEP 6: CALCULATE
finalScore = round((fidelity * 0.40) + (specificity * 0.30) + (insight * 0.30))

Respond ONLY with this JSON:
{
  "fidelity": <1-10>,
  "fidelityReasoning": "",
  "specificity": <1-10>,
  "specificityReasoning": "",
  "insight": <1-10>,
  "insightReasoning": "",
  "score": ,
  "feedback": ""
}`;

Extracting JSON from Chain-of-Thought Output

Because the critic now writes several paragraphs of reasoning before producing the JSON, JSON.parse(result.text) throws because the response isn't pure JSON anymore. Before I caught this and fixed it, the fallback value of 4 was returned silently on every parse failure, which meant every loop ran the full three iterations on every topic.

The fix scans the text for the last valid JSON object, working backwards through any matches because the JSON block always appears at the end after the reasoning:

function extractJson(text: string): any {
  try { return JSON.parse(text.trim()); } catch {}

  const matches = text.match(/\{[\s\S]*\}/g);
  if (matches) {
    for (let i = matches.length - 1; i >= 0; i--) {
      try { return JSON.parse(matches[i]); } catch {}
    }
  }

  const fenced = text.match(/```(?:json)?\s*([\s\S]*?)```/);
  if (fenced) {
    try { return JSON.parse(fenced[1].trim()); } catch {}
  }

  return null;
}

The Evaluation Bias I Almost Shipped

After the critic rebuild, things were working properly: first drafts scoring 4-6, the revision loop triggering, revisions actually improving on the previous attempt.

But a clear pattern emerged across technology topics: Mastra consistently scoring 8-9, and LangChain consistently scoring 6-7, on every single topic.

Looking at what the critic was actually rewarding revealed the problem. Source Fidelity carries 40% of the final score, and it rewards reports that cite specific named sources from the Tavily results. Mastra's reports were full of phrases like "according to Kore.ai's analysis" and "the ArXiv paper on orchestrated multi-agent systems identifies." LangChain's reports made the same points but without attributing them to specific sources.

The cause was how context flowed through each pipeline. Mastra's Agent class carries the full Tavily content (titles, URLs, content snippets) in its conversation history through the tool loop. By the time the writer agent runs, all of that source material is available in context.

The LangChain write node, on the other hand, only received state.analysis, which is the structured JSON extracted from the research: key findings, themes, and a central argument. By the time that JSON was produced, the specific source details had already been abstracted away. The writer had the conclusions but not the citations.

Both pipelines were correctly implemented according to each framework's idioms, but I had given them unequal inputs without realising it. The evaluation system was rewarding one framework for having more context rather than for producing a better report, and the consistent score gap across every technology topic was the signal: a genuine quality difference would vary by topic and draft, but a structural gap shows up the same way every time.

The fix was one change in the LangChain write node: pass state.research (the raw Tavily results) alongside state.analysis:

async function writeNode(state: PipelineStateType): Promise> {
  const prompt = `You are a research analyst writing for a technical audience.

RESEARCH (raw search results -- cite specific sources by name):
${state.research}

ANALYSIS:
${state.analysis}
\({state.feedback ? `\nCRITIC FEEDBACK FROM PREVIOUS DRAFT:\n\){state.feedback}` : ""}

${WRITER_INSTRUCTIONS}

Return ONLY the report text.`;

  const response = await retryOnFetch(() => llm.invoke(prompt));
  return { draft: response.content as string, iterations: (state.iterations ?? 0) + 1 };
}

With both writers receiving identical source material, quality scores now reflect actual writing quality. If your evaluation system consistently favours one option across many runs, the first thing to check is whether both options have equal inputs. A structural gap produces consistent results, while a genuine quality difference varies by topic and draft quality.

The Real-Time Dashboard

Running pipelines in the terminal works for your own comparisons, but it doesn't scale to a benchmark that other people can use. The dashboard needed both pipelines running in parallel, every step visible as it executes, the full prompt and response expandable per step, Tavily results with relevance score bars, token counts, a live scrolling log, and everything saved and browsable by category.

The Convex Schema

Convex was chosen specifically for real-time capabilities: its useQuery hook in React subscribes to database queries and automatically re-renders when the underlying data changes, without any polling or websocket management on your end.

The schema stores every run at three levels of granularity:

steps: defineTable({
  runId: v.id("runs"),
  pipelineResultId: v.id("pipelineResults"),
  framework: v.union(v.literal("mastra"), v.literal("langchain")),
  stepName: v.union(
    v.literal("research"), v.literal("analysis"),
    v.literal("write"), v.literal("critic")
  ),
  iterationNumber: v.number(),
  status: v.union(v.literal("running"), v.literal("complete"), v.literal("error")),
  promptSent: v.optional(v.string()),
  output: v.optional(v.string()),
  timeMs: v.optional(v.number()),
  inputTokens: v.optional(v.number()),
  outputTokens: v.optional(v.number()),
  model: v.optional(v.string()),
  tavilyQuery: v.optional(v.string()),
  tavilyResults: v.optional(v.string()),
  criticScore: v.optional(v.number()),
  criticFeedback: v.optional(v.string()),
  criticDimensions: v.optional(v.object({
    fidelity: v.number(),
    specificity: v.number(),
    insight: v.number(),
    fidelityReasoning: v.string(),
    specificityReasoning: v.string(),
    insightReasoning: v.string(),
  })),
}).index("by_pipeline_result", ["pipelineResultId"]),

The criticDimensions field stores the full G-Eval breakdown so the dashboard can render individual dimension scores with colored bars and the per-dimension reasoning text.

The Fire-and-Forget Pattern

The most important decision in the Next.js API route is returning the runId before either pipeline finishes. If you await both pipelines first, the browser sits waiting 30-60 seconds before it can even navigate to the run page, and the whole point of real-time updates is gone.

const activeTasks = new Map>();

export async function POST(req: NextRequest) {
  const { topic, category } = await req.json();

  // Create the Convex records synchronously (these are fast)
  const runId = await retryMutation(() =>
    fetchMutation(api.runs.createRun, { topic, category, status: "running" })
  );
  const mastraResultId = await retryMutation(() =>
    fetchMutation(api.pipelineResults.createPipelineResult, {
      runId, framework: "mastra", status: "running", iterations: 0,
    })
  );
  const langchainResultId = await retryMutation(() =>
    fetchMutation(api.pipelineResults.createPipelineResult, {
      runId, framework: "langchain", status: "running", iterations: 0,
    })
  );

  // Start both pipelines without awaiting them
  const task = Promise.allSettled([
    withRetry(() => runMastraPipeline(topic, buildCallbacks(runId, mastraResultId, "mastra"))),
    withRetry(() => runLangChainPipeline(topic, buildCallbacks(runId, langchainResultId, "langchain"))),
  ]).then(async () => {
    await retryMutation(() =>
      fetchMutation(api.runs.updateRunStatus, { runId, status: "complete" })
    );
    activeTasks.delete(runId as string);
  });

  // Hold a reference in the Map so Node.js doesn't garbage-collect the promise
  activeTasks.set(runId as string, task);
  return NextResponse.json({ runId });   // returns immediately
}

On Vercel, this pattern still fails because serverless functions terminate when the route handler returns, killing any background promises. The fix is using waitUntil from @vercel/functions, which tells Vercel to keep the execution context alive until the promise resolves:

import { waitUntil } from "@vercel/functions";

waitUntil(task);
return NextResponse.json({ runId });

Subscribing to Live Updates

On the run page, three Convex queries run simultaneously: the run itself, the pipeline results, and the steps for each pipeline result.

The "skip" sentinel is important here: it tells Convex to hold the subscription open without executing the query until a real argument is available. This prevents a race condition where the steps query fires before the pipeline result records have been created:

const mastraSteps = useQuery(
  api.steps.getStepsForPipelineResult,
  mastraResult ? { pipelineResultId: mastraResult._id } : "skip"
);

Deduplicating Steps After Retries

When a pipeline fails due to a TLS error and retries from the beginning, the failed attempt's step records stay in Convex alongside the successful attempt's records. The UI would render both, creating a visible gap between the research card and the rest of the steps.

The fix groups steps by stepName + iterationNumber and keeps the best version of each:

const stepMap = new Map();
[...steps]
  .sort((a, b) => (a._creationTime ?? 0) - (b._creationTime ?? 0))
  .forEach((s) => {
    const key = `\({s.stepName}-\){s.iterationNumber}`;
    const existing = stepMap.get(key);
    if (!existing) { stepMap.set(key, s); return; }
    if (s.status === "complete") { stepMap.set(key, s); return; }
    if (existing.status !== "complete") { stepMap.set(key, s); }
  });

The Live Log Auto-Scroll

Log entries are appended to the pipeline result document in Convex as an array, and the panel auto-scrolls as new entries arrive using a ref attached to an empty div at the bottom:

function LiveLogPanel({ logs }: { logs?: LogEntry[] }) {
  const endRef = useRef(null);

  useEffect(() => {
    endRef.current?.scrollIntoView({ behavior: "smooth" });
  }, [logs?.length]);

  return (
    
      {logs?.map((entry, i) => (
        
          [{fmtTs(entry.timestamp)}]
          {entry.tag}
          {entry.message}
        
      ))}
      
    
  );
}

The effect dependency is logs?.length, so the scroll triggers every time a new log entry arrives from Convex.

What the Data Actually Shows

Speed: LangChain is 25-45% faster in every run. On shorter topics the gap narrows to 7-8 seconds, but it never reverses.

I think the reason for this is structural. Mastra's Agent class initialises its tool loop manager on every step, even when no tools are called. That means internal conversation history, tool schemas, and retry infrastructure are all set up as overhead before the actual model call happens.

Across a four-step pipeline, those 2-5 seconds per step accumulate. LangGraph nodes are plain async functions, so your code runs directly, with no framework initialisation between you and the model.

Tokens: Mastra uses 1.5-2.5x more tokens. The research step alone accounted for most of that gap because LangChain's research node calls Tavily directly without invoking an LLM at all.

On more typical topics, Mastra runs around 6,200 tokens and LangChain around 3,900. The gap scales with how much content Tavily returns, because that content flows into Mastra's agent conversation history on every subsequent step.

Quality: After fixing the evaluation bias, scores vary meaningfully by topic rather than by framework. Both produce high-scoring reports when the Tavily results are specific and rich. Both struggle on vague or biographical topics where the search results are generic.

A first draft scoring 7 or 8 means the research was strong and the writer made specific grounded claims. A 4 or 5 means the research returned thin results and the writer defaulted to generic observations, and the revision loop runs until either the draft improves or the iteration limit is hit.

The tradeoff: Mastra handles orchestration complexity in the framework so you don't have to. You write .dowhile() instead of a conditional edge, typed step schemas instead of a shared mutable state object, and the framework manages conversation history and tool execution. The cost is a consistent token and latency overhead on every step.

LangChain gives you the graph execution engine and leaves everything else to you: more explicit wiring to write, but leaner execution and precise control over every token that enters each model call.

Try it Yourself

The live demo is at mastra-vs-langchain.vercel.app and the complete source code for this comparison is at github.com/sholajegede/mastra-vs-langchain. If it helped you, consider giving it a star.

git clone https://github.com/sholajegede/mastra-vs-langchain.git
cd mastra-vs-langchain
npm install
cp .env.example .env
# Add ANTHROPIC_API_KEY and TAVILY_API_KEY
npx convex dev   # Terminal 1
npm run web      # Terminal 2

Open localhost:3000, enter a topic, pick a category, and run both. Every step is visible as it happens, every token is counted, and the history page stores all previous runs by category.

If you want to take this comparison further by adding CrewAI, CopilotKit, or any other framework to the benchmark, the PipelineCallbacks interface in packages/shared is the only contract you need to implement.

If this tutorial was useful, feel free to share it with others who might benefit. I’d really appreciate your thoughts. You can mention me on X at @wani_shola or connect with me on LinkedIn.

How to Build and Deploy Tetris Inside ChatGPT: A Complete Guide to the Vercel ChatGPT Apps SDK with TypeScript, Convex, and Kinde OAuth

Shola Jegede — Sat, 17 Jan 2026 09:00:00 +0000

Imagine playing a fully functional game of Tetris without leaving your ChatGPT conversation: rotating pieces, clearing lines, competing on leaderboards – all within the chat interface you already use every day.

With the Vercel ChatGPT Apps SDK and the Model Context Protocol (MCP), you can embed rich, interactive applications directly into ChatGPT.

In this tutorial, you'll build a production-ready Tetris game that lives inside ChatGPT, complete with user authentication, real-time leaderboards, and a replay system.

What You'll Build
Why This Matters
Prerequisites
Tech Stack Overview
Understanding the Architecture
Key Concepts
Project Setup & Initial Configuration
Setting Up the Convex Backend
Building the Tetris Game Engine
Implementing Kinde OAuth Authentication
Building the MCP Integration
Building the Supporting Features
Deploying to Vercel
Registering with ChatGPT
Finishing Up
Troubleshooting
Final Data Flow
Conclusion

What You'll Build

By the end of this tutorial, you'll have a full-stack application with:

Core gameplay: A fully playable Tetris game with smooth animations, keyboard and touch controls, real-time scoring, and level progression.
User Features: OAuth authentication via Kinde, persistent user profiles, public and private game modes, and a replay system that records every move.
Social and competitive feel: A global leaderboard, replay viewer, and ChatGPT integration that lets you start games, check scores, and review replays through natural conversation.
Technical architecture: Next.js 16 frontend with React 19 and Shadcn UI, Convex real-time database, MCP integration for ChatGPT tool registration, and production deployment on Vercel.

The user experience looks like this: say "Start a new Tetris game" in ChatGPT, an embedded game widget appears, and you play using arrow keys or on-screen controls. When the game ends, ChatGPT updates your score. Then you can ask "Show me the top 10 players" and the leaderboard appears — all in a single conversational flow.

Why This Matters

The ChatGPT Apps SDK represents a fundamental shift in how we think about AI applications. Instead of building separate interfaces or forcing users to navigate between ChatGPT and your app, you bring your application into the conversation.

This means zero learning curve (users already know ChatGPT), contextual AI intelligence, reduced friction (no app downloads or extra accounts), and access to 800M weekly active users.

Prerequisites

Required skills

To follow along, you'll need JavaScript/TypeScript fundamentals (ES6+, async/await), React basics (components, hooks, props), basic Next.js familiarity, and command-line comfort.

Required accounts and tools

Node.js 20+ and pnpm 10+
ChatGPT Plus subscription ($20/month as of January 2026)
Vercel account (free tier works)
Convex account (free tier: 1GB storage, 1M function calls/month)
Kinde account (free tier: 10,500 monthly active users)

Tech Stack Overview

Let's quickly go over the tools we'll be using, and why we'll be using them, so you're familiar with our tech stack.

Frontend Tools

Next.js 16 + React 19 + Shadcn UI: App Router, serverless API routes, optimized builds via Turbopack, and React 19's improved rendering.

Backend Tools

Convex: Replaces traditional databases and ORMs with a TypeScript-native real-time database. Here's why it matters:

// Traditional approach:
const game = await db.query("SELECT * FROM games WHERE id = ?", [gameId]);
game.score += 100;
await db.query("UPDATE games SET score = ? WHERE id = ?", [game.score, gameId]);
// Manually notify clients via WebSockets...

// Convex approach:
export const updateScore = mutation({
  args: { gameId: v.id("games"), points: v.number() },
  handler: async (ctx, args) => {
    await ctx.db.patch(args.gameId, { score: args.score + args.points });
    // All subscribed clients automatically receive the update
  }
});

Authentication – Kinde OAuth 2.0: Handles secure JWT token generation, user profile management, and multiple providers. Simpler than Auth0, with a more generous free tier (10,500 MAU vs. 7,500).

Deployment – Vercel: Zero-config Next.js deployment, automatic HTTPS, global CDN, and preview deployments for every PR.

ChatGPT Integration – MCP (Model Context Protocol): The bridge between ChatGPT and your application. Defines tools ChatGPT can call, resources it can read, and suggested phrases for users. The mcp-handler npm package handles protocol negotiation, message parsing, OAuth token extraction, and CORS headers:

import { createMCPHandler } from 'mcp-handler';

export const { GET, POST } = createMCPHandler({
  name: "Tetris Game Server",
  version: "1.0.0",
  setupServer: async (server) => {
    // Register all your tools here
  }
});

Understanding the Architecture

Before writing a line of code, you need a mental model of how all the pieces fit together. This section moves from high-level system design down to specific component interactions.

The Vercel ChatGPT App Template Foundation

The Vercel ChatGPT Apps template solves several hard problems out of the box: a pre-configured Next.js 16 setup with Turbopack, an integrated MCP protocol handler, OAuth discovery endpoints, CORS configuration for ChatGPT's iframe security model, and a widget rendering system.

The most important configuration file is next.config.ts. ChatGPT renders your app in an iframe from a different origin, so without permissive CORS headers, browsers block the cross-origin requests your game needs:

// next.config.ts
const nextConfig: NextConfig = {
  async headers() {
    return [
      {
        source: "/:path*",
        headers: [
          { key: "Access-Control-Allow-Origin", value: "*" },
          { key: "Access-Control-Allow-Methods", value: "GET,POST,PUT,DELETE,OPTIONS" },
          { key: "Access-Control-Allow-Headers", value: "*" },
        ],
      },
    ];
  },
};

The template also provides a baseURL helper that's critical for OAuth redirects:

// lib/baseURL.ts
export const baseURL =
  process.env.NODE_ENV === "development"
    ? "http://localhost:3000"
    : "https://" +
      (process.env.VERCEL_ENV === "production"
        ? process.env.VERCEL_PROJECT_PRODUCTION_URL
        : process.env.VERCEL_BRANCH_URL || process.env.VERCEL_URL);

This ensures OAuth callbacks work in local development, preview deployments, and production without hardcoding URLs.

Three-Tier Architecture

Our Tetris application uses a classic three-tier architecture with modern serverless components:

┌──────────────────────────────────────────────────────┐
│                 TIER 1: PRESENTATION                 │
│  Chat Interface  ◄────────  Widget (iframe)          │
│  (natural language)         (React events)           │
└────────────────────────┬─────────────────────────────┘
                         │ MCP (JSON-RPC) / HTTP
┌────────────────────────▼─────────────────────────────┐
│                TIER 2: APPLICATION                   │
│  MCP Route     │    API Routes    │   React Pages    │
│  /app/mcp      │    /app/api/*    │   /app/tetris/*  │
└────────────────────────┬─────────────────────────────┘
                         │ Convex SDK
┌────────────────────────▼─────────────────────────────┐
│                   TIER 3: DATA                       │
│  Users │ Games │ Replays │ Leaderboard               │
│  Convex Functions (mutations & queries)              │
└──────────────────────────────────────────────────────┘

Authentication flows horizontally across all tiers. The key insight: ChatGPT handles steps 1–5 of the OAuth flow automatically (redirect to Kinde, user authenticates, redirect back with code, exchange for token). Your Next.js app only handles steps 6–10: validation and user management.

Component Relationships and Data Flow

Here's the file structure you'll build:

/app
  /mcp/.well-known/oauth-protected-resource/route.ts
  /mcp/route.ts                    # MCP server + tool registration
  /api/create-game/route.ts        # HTTP endpoint for game creation
  /lib/kinde.ts                    # Kinde token validation
  /lib/mcpAuth.ts                  # MCP-specific auth helpers
  /tetris/play/page.tsx            # Main game interface
  /tetris/leaderboard/page.tsx     # Top scores table
  /tetris/replays/page.tsx         # Replay browser

/components/tetris/
  GameBoard.tsx                    # Core game logic + rendering
  Leaderboard.tsx                  # Leaderboard table component
  ReplayViewer.tsx                 # Replay playback component

/convex/
  schema.ts                        # Database table definitions
  games.ts                         # Game CRUD operations
  users.ts                         # User management
  replays.ts                       # Replay storage + retrieval
  leaderboards.ts                  # Top scores queries

The most important relationship is GameBoard.tsx to Convex. When a game starts, the MCP route creates a game in Convex and returns a widget URI. ChatGPT renders GameBoard.tsx in an iframe, which loads game state from Convex via useQuery.

The user plays locally (no round-trips for each move), actions are recorded in a ref, and when the game ends, everything syncs to Convex in a single mutation.

Leaderboard real-time updates demonstrate why Convex shines:

// components/tetris/Leaderboard.tsx
export default function Leaderboard() {
  // Re-runs automatically whenever leaderboard data changes
  const entries = useQuery(api.leaderboards.listTop, { limit: 20 }) || [];
  
  const userIds = entries.map((e: any) => e.userId).filter(Boolean);
  const users = useQuery(
    api.users.getMultipleById, 
    userIds.length > 0 ? { userIds } : "skip"
  );

  const userMap = new Map();
  if (users) {
    users.forEach((user: any) => {
      if (user) userMap.set(user._id, user);
    });
  }

  return (
    
      Leaderboard
      
        {entries.map((e: any, idx: number) => {
          const user = userMap.get(e.userId);
          const displayName = user 
            ? (user.displayName || `\({user.firstName || ''} \){user.lastName || ''}`.trim() || user.email)
            : 'Anonymous';
          
          return (
            
              {displayName}
              {e.score}
            
          );
        })}
      
    
  );
}

When someone finishes a game elsewhere, their GameBoard calls finishGame, Convex updates the leaderboards table, and your Leaderboard component re-renders automatically with new data. No polling, no WebSockets, no manual refresh code.

Key Concepts

MCP (Model Context Protocol)

This is a JSON-RPC protocol that defines how AI assistants interact with external applications. It has three primitives:

Tools: Functions the AI can call (for example, start_game, finish_game)
Resources: Data the AI can read (for example, leaderboard entries as widgets)
Prompts: Suggested phrases for users

When you register your app, ChatGPT fetches your MCP manifest and discovers available tools. When a user types "start a game," ChatGPT's language model matches the intent to start_game and calls it automatically.

The complete tool execution lifecycle is:

The user types natural language
ChatGPT calls your MCP endpoint via POST with the tool name and arguments
Your handler validates OAuth, creates a game in Convex, and returns the widget HTML
ChatGPT renders the widget in the chat interface
The user plays, and the widget calls finish_game when done
ChatGPT displays the results in chat

Widgets

These are full HTML documents rendered in sandboxed iframes. Your Next.js pages become widgets via the getAppsSdkCompatibleHtml helper. The text/html+skybridge MIME type tells ChatGPT to render the content as an interactive widget rather than plain text.

Tool registration

This uses Zod schemas for input validation and security schemes to control authentication requirements.

registerTool takes three things: the tool name, a configuration object describing the tool's inputs, security requirements, and widget metadata, and an async handler function that runs when ChatGPT calls the tool.

The inputSchema uses Zod to define and validate what arguments ChatGPT can pass in. The securitySchemes array controls whether authentication is required. The _meta field tells ChatGPT to render the tool's response as an interactive widget rather than plain text.

s.registerTool(
    "start_game",
    {
      securitySchemes: [
        { type: "noauth" }, // Allow anonymous play
        { type: "oauth2", scopes: ["profile"] },
      ],
      title: "Start Game",
      description:
        "Start a new Tetris game (creates a game record and opens the play widget). User will be associated if authenticated.",
      inputSchema: {
        public: z
          .boolean()
          .optional()
          .describe("Whether the game is public for spectating"),
        seed: z
          .number()
          .optional()
          .describe("Optional seed for deterministic play"),
      },
      _meta: widgetMeta(playWidget),
    },
  async (args: any, context: any) => { /* handler */ }
);

Multiple security schemes mean OR logic and users can play anonymously OR authenticated. A single scheme makes authentication required.

A Complete Request Flow

To make the architecture concrete, here's a full trace when an authenticated user starts a public game:

The user says "Start a public Tetris game"
ChatGPT parses intent, checks for existing OAuth token
ChatGPT POSTs to /mcp with Authorization: Bearer and { "method": "tools/call", "params": { "name": "start_game", "arguments": { "public": true } } }
The Next.js MCP route extracts and validates the token via Kinde JWKS
Next.js calls api.users.upsertLinkedAccount in Convex, receives a userId
Next.js calls api.games.createGame in Convex with the userId, receives a gameId
Next.js renders widget HTML for /tetris/play?gameId=
The Widget HTML is returned to ChatGPT in MCP response
ChatGPT renders the widget and GameBoard.tsx mounts and fetches game state
The user plays, the score updates locally, and actions are recorded in a ref
The game ends. GameBoard calls api.games.finishGame which atomically creates replay, updates leaderboard, updates user stats.
Convex reactivity pushes leaderboard updates to all subscribed clients
GameBoard calls useSendMessage to post results back to the chat thread

Project Setup & Initial Configuration

By the end of this section, you'll have a running Next.js app, a connected Convex database, Kinde OAuth configured, and all environment variables in place.

Install Required Tools

Verify your Node.js version first:

node --version   # Should be v24.x or higher
pnpm --version   # Should be v10.x or higher

If pnpm isn't installed:

npm install -g pnpm

Clone the Vercel ChatGPT Apps Template

pnpm create next-app@latest tetris-chatgpt-app \
  --example https://github.com/vercel-labs/chatgpt-apps-sdk-nextjs-starter

cd tetris-chatgpt-app
pnpm install

Install Project Dependencies

Add all packages needed for the complete application:

# Real-time database
pnpm add convex@^1.29.3

# MCP handler
pnpm add mcp-handler@^1.0.2

# Kinde OAuth token validation
pnpm add jose@^6.1.3

# Radix UI primitives (used by Shadcn)
pnpm add @radix-ui/react-dialog@^1.1.15 \
         @radix-ui/react-label@^2.1.8 \
         @radix-ui/react-select@^2.2.6 \
         @radix-ui/react-slot@^1.2.4 \
         @radix-ui/react-tabs@^1.1.13

# Utilities and UI
pnpm add class-variance-authority@^0.7.1 \
         clsx@^2.1.1 \
         lucide-react@^0.555.0 \
         sonner@^2.0.7 \
         tailwind-merge@^3.4.0 \
         zod@3.24.2 \
         next-themes@^0.4.6 \
         @modelcontextprotocol/sdk@^1.20.0

# Dev dependencies
pnpm add -D @tailwindcss/postcss@^4 tailwindcss@^4 tw-animate-css@^1.4.0

Set Up Convex

pnpm add -g convex
pnpm convex dev

The interactive prompt will ask you to create a new project. After setup, Convex creates a convex/ directory, a .env.local file with your deployment URL, and starts watching for schema changes. Keep this terminal running throughout development.

Add the Convex React provider. Create app/provider.tsx:

"use client";

import { ReactNode } from "react";
import { ConvexProvider, ConvexReactClient } from "convex/react";

const convex = new ConvexReactClient(process.env.NEXT_PUBLIC_CONVEX_URL!);

export function ConvexClientProvider({ children }: { children: ReactNode }) {
  return {children};
}

Then wrap your app in app/layout.tsx:

import { ConvexClientProvider } from "./providers";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    
      
        {children}
      
    
  );
}

Set Up Kinde OAuth

Go to kinde.com, create an account, then create a new back-end web application named "Tetris ChatGPT App."

In your application's settings, add these allowed callback URLs:

https://localhost:3000/api/auth/callback
https://chatgpt.com/connector_platform_oauth_redirect

And these allowed logout redirect URLs:

https://tetris-chatgpt-app.vercel.app
https://chatgpt.com

Copy your Domain, Client ID, and Client Secret from the application details page.

Now create app/lib/kinde.ts:

import { createRemoteJWKSet, jwtVerify } from 'jose';

const KINDE_ISSUER = process.env.KINDE_ISSUER!;
const MCP_AUDIENCE = process.env.MCP_AUDIENCE!;

let cachedJWKS: ReturnType | null = null;

async function getJWKS() {
  if (!cachedJWKS) {
    cachedJWKS = createRemoteJWKSet(
      new URL(`${KINDE_ISSUER}/.well-known/jwks.json`)
    );
  }
  return cachedJWKS;
}

export async function validateKindeToken(token: string) {
  if (!token) throw new Error('No token provided');

  const JWKS = await getJWKS();
  const { payload } = await jwtVerify(token, JWKS, {
    issuer: KINDE_ISSUER,
    audience: MCP_AUDIENCE,
  });

  return payload as {
    sub: string;
    email?: string;
    given_name?: string;
    family_name?: string;
    picture?: string;
    exp: number;
    iat: number;
  };
}

export async function getKindeUserProfile(token: string) {
  const payload = await validateKindeToken(token);
  return {
    id: payload.sub,
    email: payload.email,
    name: [payload.given_name, payload.family_name].filter(Boolean).join(' ') || 'Anonymous',
    picture: payload.picture,
  };
}

Create the OAuth discovery endpoint at app/mcp/.well-known/oauth-protected-resource/route.ts:

import { NextResponse } from 'next/server';

export async function GET() {
  return NextResponse.json({
    resource: process.env.MCP_RESOURCE!,
    authorization_servers: [process.env.KINDE_ISSUER!],
    scopes_supported: ['openid', 'profile', 'email'],
    bearer_methods_supported: ['header'],
  });
}

This endpoint tells ChatGPT where to send users to authenticate. Without it, ChatGPT can't discover your OAuth configuration.

Create app/lib/utils.ts:

import { clsx, type ClassValue } from "clsx";
import { twMerge } from "tailwind-merge";

export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs));
}

Environment Variables

Your complete .env.local should look like this:

# Convex (auto-generated by pnpm convex dev)
CONVEX_DEPLOYMENT=dev:your-deployment-name
NEXT_PUBLIC_CONVEX_URL=https://your-deployment.convex.cloud

# Kinde OAuth
KINDE_ISSUER=https://yourcompany.kinde.com
KINDE_CLIENT_ID=your-client-id
KINDE_CLIENT_SECRET=your-client-secret

# MCP settings (update after deploying to Vercel)
MCP_AUDIENCE=http://localhost:3000/mcp
MCP_RESOURCE=http://localhost:3000
MCP_DOC_URL=http://localhost:3000/mcp-docs

Make sure .env.local is in your .gitignore and it should be by default in the template.

Verify Everything Works

Open three terminals:

# Terminal 1
pnpm convex dev

# Terminal 2
pnpm dev

# Terminal 3 — test the OAuth discovery endpoint
curl http://localhost:3000/mcp/.well-known/oauth-protected-resource
# Expected: { "resource": "...", "authorization_servers": [...], ... }

Open http://localhost:3000 in your browser. If it loads without console errors and the OAuth endpoint returns JSON, your setup is complete.

Common issues:

"Cannot find module 'convex/react'" – run pnpm install and restart the dev server
"NEXT_PUBLIC_CONVEX_URL is not defined" – run pnpm convex dev to regenerate .env.local
"Failed to verify token signature" – ensure KINDE_ISSUER has no trailing slash

Set Up Vercel

Install the CLI and link your project so deployment is one command away later:

pnpm add -g vercel
vercel login
vercel link

Add your environment variables to Vercel now:

vercel env add NEXT_PUBLIC_CONVEX_URL
vercel env add KINDE_ISSUER
vercel env add KINDE_CLIENT_ID
vercel env add KINDE_CLIENT_SECRET

You'll update the MCP-specific variables after your first deployment once you have a production URL.

Setting Up the Convex Backend

This section builds the complete data layer: schema, mutations, queries, and real-time reactivity. By the end, you'll have a fully functional backend that automatically pushes updates to every connected client the moment data changes — no polling, no manual refresh logic.

Database Schema Design

The schema is the contract for everything your app stores. Open convex/schema.ts and replace its contents with the full schema below. Take a moment to read through the table definitions before pasting — understanding what each table stores and why will make the mutation code much easier to follow.

Open convex/schema.ts and replace its contents with the full schema:

import { defineSchema, defineTable } from "convex/server";
import { v } from "convex/values";

export default defineSchema({
  users: defineTable({
    email: v.string(),
    displayName: v.optional(v.string()),
    firstName: v.optional(v.string()),
    lastName: v.optional(v.string()),
    imageUrl: v.optional(v.string()),
    imageStorageId: v.optional(v.id("_storage")),
    updatedAt: v.number(),
  }).index("by_email", ["email"]),

  linkedAccounts: defineTable({
    provider: v.string(),
    subject: v.string(),
    userId: v.id("users"),
    profile: v.optional(v.object({})),
    updatedAt: v.number(),
  }).index("by_provider_subject", ["provider", "subject"]).index("by_user", ["userId"]),

  games: defineTable({
    userId: v.optional(v.id("users")),
    status: v.union(
      v.literal("active"),
      v.literal("paused"),
      v.literal("finished"),
      v.literal("abandoned")
    ),
    score: v.number(),
    level: v.number(),
    linesCleared: v.number(),
    board: v.array(v.number()),
    currentPiece: v.optional(
      v.object({ type: v.string(), rotation: v.number(), x: v.number(), y: v.number() })
    ),
    nextQueue: v.optional(v.array(v.string())),
    holdPiece: v.optional(v.string()),
    seed: v.optional(v.number()),
    replayId: v.optional(v.id("replays")),
    public: v.optional(v.boolean()),
    updatedAt: v.number(),
  })
    .index("by_user", ["userId"])
    .index("by_status", ["status"])
    .index("by_score", ["score"]),

  replays: defineTable({
    gameId: v.id("games"),
    userId: v.optional(v.id("users")),
    actions: v.array(v.object({ t: v.number(), a: v.string(), p: v.optional(v.object({})) })),
    durationMs: v.number(),
  }).index("by_game", ["gameId"]),

  leaderboards: defineTable({
    userId: v.id("users"),
    score: v.number(),
    level: v.number(),
    linesCleared: v.number(),
  }).index("by_score", ["score"]),
});

A few design decisions worth calling out:

linkedAccounts is a separate table, so one user can authenticate via multiple OAuth providers without duplicating their profile. The provider + subject pair (for example, "kinde" + "kinde|2151678548") uniquely identifies an OAuth identity. The userId field is a foreign key pointing to the single users row that represents the human behind potentially many auth accounts.

The replays.actions array uses a compact format — { t, a } stands for timestamp and action code — so an entire game fits in roughly 50KB of JSON rather than megabytes of full board snapshots taken at every tick.

Indexes are not optional. Without by_email on users, finding a returning user requires a full table scan that grows linearly with your user count. With the index, lookups are O(log n) regardless of scale. Every table that will be queried by a specific field needs an index on that field.

User Management

Create convex/users.ts. This file is the backbone of your identity system — it handles looking users up, creating new ones, and most importantly, linking OAuth provider identities to your own user records.

import { query, mutation } from "./_generated/server";
import { v } from "convex/values";

export const getByEmail = query({
  args: { email: v.string() },
  handler: async (ctx, { email }) => {
    return await ctx.db
      .query("users")
      .withIndex("by_email", (q) => q.eq("email", email))
      .first();
  },
});

export const getById = query({
  args: { userId: v.id("users") },
  handler: async (ctx, { userId }) => {
    return await ctx.db.get(userId);
  },
});

export const getMultipleById = query({
  args: { userIds: v.array(v.id("users")) },
  handler: async (ctx, { userIds }) => {
    const users = await Promise.all(
      userIds.map(id => ctx.db.get(id))
    );
    return users;
  },
});

export const createOrUpdate = mutation({
  args: {
    email: v.string(),
    displayName: v.optional(v.string()),
    firstName: v.optional(v.string()),
    lastName: v.optional(v.string()),
    imageUrl: v.optional(v.string()),
  },
  handler: async (ctx, args) => {
    const now = Date.now();

    const existingUser = await ctx.db
      .query("users")
      .withIndex("by_email", (q) => q.eq("email", args.email))
      .first();

    if (existingUser) {
      // Update existing user — only overwrite fields that are actually provided,
      // so a partial update won't clear data you didn't intend to touch.
      return await ctx.db.patch(existingUser._id, {
        displayName: args.displayName ?? existingUser.displayName,
        firstName: args.firstName ?? existingUser.firstName,
        lastName: args.lastName ?? existingUser.lastName,
        imageUrl: args.imageUrl ?? existingUser.imageUrl,
        updatedAt: now,
      });
    }

    // First time we've seen this email — create a new user record
    return await ctx.db.insert("users", {
      email: args.email,
      displayName: args.displayName,
      firstName: args.firstName,
      lastName: args.lastName,
      imageUrl: args.imageUrl,
      updatedAt: now,
    });
  },
});

export const patchProfile = mutation({
  args: {
    userId: v.id("users"),
    displayName: v.optional(v.string()),
    firstName: v.optional(v.string()),
    lastName: v.optional(v.string()),
    imageUrl: v.optional(v.string()),
    imageStorageId: v.optional(v.id("_storage")),
  },
  handler: async (ctx, args) => {
    // Build the patch object dynamically so we only write fields that were passed in
    const patch: Record = { updatedAt: Date.now() };
    if (args.displayName !== undefined) patch.displayName = args.displayName;
    if (args.firstName !== undefined) patch.firstName = args.firstName;
    if (args.lastName !== undefined) patch.lastName = args.lastName;
    if (args.imageUrl !== undefined) patch.imageUrl = args.imageUrl;
    if (args.imageStorageId !== undefined) patch.imageStorageId = args.imageStorageId;

    return await ctx.db.patch(args.userId, patch);
  },
});

export const upsertLinkedAccount = mutation({
  args: {
    provider: v.string(),
    subject: v.string(),
    profile: v.optional(v.object({})),
  },
  handler: async (ctx, { provider, subject, profile }) => {
    const now = Date.now();

    // Step 1: Check if we've seen this exact OAuth identity before
    const linked = await ctx.db
      .query("linkedAccounts")
      .withIndex("by_provider_subject", (q) => q.eq("provider", provider).eq("subject", subject))
      .first();

    if (linked) {
      // Already linked — just refresh the cached profile data and return the existing userId
      await ctx.db.patch(linked._id, { profile: profile ?? linked.profile, updatedAt: now });
      return linked.userId;
    }

    // Step 2: New OAuth identity — try to find an existing Convex user by email
    // so we don't create a duplicate account if this person signed up a different way
    let user = null;
    const email = profile && (profile as any).email;
    if (email) {
      user = await ctx.db
        .query("users")
        .withIndex("by_email", (q) => q.eq("email", email))
        .first();
    }

    // Step 3: If no match by email, create a brand new user record
    if (!user) {
      const created = await ctx.db.insert("users", {
        email: email ?? `\({provider}:\){subject}`,
        displayName: profile && (profile as any).name,
        imageUrl: profile && (profile as any).picture,
        updatedAt: now,
      });
      user = created;
    }
    
    const userId = typeof user === "string" ? user : user._id;

    // Step 4: Record the link between this OAuth identity and the Convex user
    await ctx.db.insert("linkedAccounts", {
      provider,
      subject,
      userId: userId,
      profile: profile ?? {},
      updatedAt: now,
    });

    return userId;
  },
});

upsertLinkedAccount is the most important mutation in this file — it's the OAuth entry point for your entire app. Every time a user authenticates via Kinde, you call this function and it runs through four steps:

Look up the OAuth identity (provider + subject) in linkedAccounts
If found, update the cached profile and return the existing userId — same user, no new records
If not found, try to match by email in case this user already signed up a different way
If still no match, create a new user and link the OAuth identity to it

This design means a user who authenticates with Google and later with GitHub ends up with one users record and two linkedAccounts rows, both pointing to the same Convex user ID.

Game Management

Create convex/games.ts. This file manages the full lifecycle of a game — creation, incremental state updates, and the final atomic write when a game ends.

import { query, mutation } from "./_generated/server";
import { v } from "convex/values";

export const createGame = mutation({
  args: {
    userId: v.optional(v.id("users")),
    public: v.optional(v.boolean()),
    seed: v.optional(v.number()),
    board: v.optional(v.array(v.number())),
    currentPiece: v.optional(v.object({ type: v.string(), rotation: v.number(), x: v.number(), y: v.number() })),
    nextQueue: v.optional(v.array(v.string())),
    holdPiece: v.optional(v.string()),
  },
  handler: async (ctx, args) => {
    const now = Date.now();
    const inserted = await ctx.db.insert("games", {
      userId: args.userId,
      status: "active",
      score: 0,
      level: 1,
      linesCleared: 0,
      board: args.board ?? [],
      currentPiece: args.currentPiece,
      nextQueue: args.nextQueue ?? [],
      holdPiece: args.holdPiece,
      seed: args.seed,
      replayId: undefined,
      public: args.public ?? false,
      updatedAt: now,
    });

    return inserted;
  },
});

export const getGame = query({
  args: { gameId: v.id("games") },
  handler: async (ctx, { gameId }) => {
    return await ctx.db.get(gameId);
  },
});

export const listByUser = query({
  args: { userId: v.id("users"), status: v.optional(v.string()) },
  handler: async (ctx, { userId, status }) => {
    const q = ctx.db.query("games").withIndex("by_user", (q) => q.eq("userId", userId));
    const all = await q.collect();
    if (status) return all.filter((g: any) => g.status === status);
    return all;
  },
});

export const patchGame = mutation({
  args: {
    gameId: v.id("games"),
    status: v.optional(v.union(v.literal("active"), v.literal("paused"), v.literal("finished"), v.literal("abandoned"))),
    score: v.optional(v.number()),
    level: v.optional(v.number()),
    linesCleared: v.optional(v.number()),
    board: v.optional(v.array(v.number())),
    currentPiece: v.optional(v.object({ type: v.string(), rotation: v.optional(v.number()), x: v.number(), y: v.number() })),
    nextQueue: v.optional(v.array(v.string())),
    holdPiece: v.optional(v.string()),
    seed: v.optional(v.number()),
    replayId: v.optional(v.id("replays")),
    public: v.optional(v.boolean()),
  },
  handler: async (ctx, args) => {
    // Build a patch object with only the fields that were explicitly provided.
    // This prevents an accidental undefined from overwriting real data.
    const patch: Record = { updatedAt: Date.now() };
    if (args.status !== undefined) patch.status = args.status;
    if (args.score !== undefined) patch.score = args.score;
    if (args.level !== undefined) patch.level = args.level;
    if (args.linesCleared !== undefined) patch.linesCleared = args.linesCleared;
    if (args.board !== undefined) patch.board = args.board;
    if (args.currentPiece !== undefined) patch.currentPiece = args.currentPiece;
    if (args.nextQueue !== undefined) patch.nextQueue = args.nextQueue;
    if (args.holdPiece !== undefined) patch.holdPiece = args.holdPiece;
    if (args.seed !== undefined) patch.seed = args.seed;
    if (args.replayId !== undefined) patch.replayId = args.replayId;
    if (args.public !== undefined) patch.public = args.public;

    return await ctx.db.patch(args.gameId, patch);
  },
});

export const setStatus = mutation({
  args: { gameId: v.id("games"), status: v.union(v.literal("active"), v.literal("paused"), v.literal("finished"), v.literal("abandoned")) },
  handler: async (ctx, { gameId, status }) => {
    return await ctx.db.patch(gameId, { status, updatedAt: Date.now() });
  },
});

export const finishGame = mutation({
  args: {
    gameId: v.id("games"),
    score: v.number(),
    level: v.number(),
    linesCleared: v.number(),
    replayActions: v.optional(v.array(v.object({ t: v.number(), a: v.string(), p: v.optional(v.object({})) }))),
    durationMs: v.optional(v.number()),
    userId: v.optional(v.id("users")),
  },
  handler: async (ctx, { gameId, score, level, linesCleared, replayActions, durationMs, userId }) => {
    const now = Date.now();
    const game = await ctx.db.get(gameId);
    if (!game) throw new Error("Game not found");

    // Use the userId passed in, or fall back to the one stored on the game record
    const finalUserId = userId ?? game.userId;

    let replayId = game.replayId ?? undefined;

    // Save the replay if any actions were recorded during the game
    if (replayActions && replayActions.length > 0) {
      const insertedReplay = await ctx.db.insert("replays", {
        gameId,
        userId: finalUserId,
        actions: replayActions,
        durationMs: durationMs ?? 0,
      });
      replayId = insertedReplay;
    }

    // Mark the game finished with final stats
    await ctx.db.patch(gameId, {
      userId: finalUserId,
      status: "finished",
      score,
      level,
      linesCleared,
      replayId,
      updatedAt: now,
    });

    // Only add a leaderboard entry for authenticated users — anonymous games
    // are saved but don't appear in the public rankings
    if (finalUserId) {
      await ctx.db.insert("leaderboards", {
        userId: finalUserId,
        score,
        level,
        linesCleared,
      });
    }

    return await ctx.db.get(gameId);
  },
});

export const deleteGame = mutation({
  args: { gameId: v.id("games") },
  handler: async (ctx, { gameId }) => {
    return await ctx.db.delete(gameId);
  },
});

export const listPublicFinishedGames = query({
  args: { limit: v.optional(v.number()) },
  handler: async (ctx, { limit }) => {
    const finished = await ctx.db.query("games").withIndex("by_status", (q) => q.eq("status", "finished")).collect();
    const publicOnes = (finished as any[]).filter((g) => g.public === true);
    if (limit) return publicOnes.slice(0, limit);
    return publicOnes;
  },
});

export const getTopLeaderboard = query({
  args: { limit: v.optional(v.number()) },
  handler: async (ctx, { limit }) => {
    const all = await ctx.db.query("leaderboards").withIndex("by_score", (q) => q).collect();
    const sorted = (all as any[]).sort((a, b) => b.score - a.score);
    if (limit) return sorted.slice(0, limit);
    return sorted;
  },
});

finishGame is the most important mutation in the entire app. All of these writes — creating the replay, updating the game's status, and inserting the leaderboard entry — happen inside a single Convex mutation, which means they run in a single transaction.

Either all of them succeed or none of them commit. You'll never end up with a finished game that has no leaderboard entry, or a leaderboard entry pointing to a game that was never marked finished.

Replay and Leaderboard Functions

Create convex/replays.ts. The key query to understand here is getRecentReplaysWithDetails, which joins replay records with their related game and user data in one call. Convex doesn't have SQL-style JOINs, so the idiomatic pattern is to fetch the related IDs in one query and then resolve them with Promise.all.

import { query, mutation } from "./_generated/server";
import { v } from "convex/values";

export const createReplay = mutation({
  args: {
    gameId: v.id("games"),
    userId: v.optional(v.id("users")),
    actions: v.array(v.object({ t: v.number(), a: v.string(), p: v.optional(v.object({})) })),
    durationMs: v.number(),
  },
  handler: async (ctx, { gameId, userId, actions, durationMs }) => {
    return await ctx.db.insert("replays", {
      gameId,
      userId,
      actions,
      durationMs,
    });
  },
});

export const getReplay = query({
  args: { replayId: v.id("replays") },
  handler: async (ctx, { replayId }) => {
    const replay = await ctx.db.get(replayId);
    if (!replay) return null;
    // Eagerly load the related game and user so the viewer component
    // gets everything it needs in one round trip
    const game = await ctx.db.get(replay.gameId);
    const user = replay.userId ? await ctx.db.get(replay.userId) : null;
    return { ...replay, game, user };
  },
});

export const listByGame = query({
  args: { gameId: v.id("games") },
  handler: async (ctx, { gameId }) => {
    return await ctx.db
      .query("replays")
      .withIndex("by_game", (q) => q.eq("gameId", gameId))
      .collect();
  },
});

export const listByUser = query({
  args: { userId: v.id("users") },
  handler: async (ctx, { userId }) => {
    return await ctx.db
      .query("replays")
      .filter((q) => q.eq(q.field("userId"), userId))
      .collect();
  },
});

export const patchReplay = mutation({
  args: {
    replayId: v.id("replays"),
    actions: v.optional(v.array(v.object({ t: v.number(), a: v.string(), p: v.optional(v.object({})) }))),
    durationMs: v.optional(v.number()),
  },
  handler: async (ctx, { replayId, actions, durationMs }) => {
    const patch: Record = {};
    if (actions !== undefined) patch.actions = actions;
    if (durationMs !== undefined) patch.durationMs = durationMs;
    return await ctx.db.patch(replayId, patch);
  },
});

export const deleteReplay = mutation({
  args: { replayId: v.id("replays") },
  handler: async (ctx, { replayId }) => {
    return await ctx.db.delete(replayId);
  },
});

export const getRecentReplays = query({
  args: { limit: v.optional(v.number()) },
  handler: async (ctx, { limit }) => {
    return await ctx.db
      .query("replays")
      .order("desc")
      .take(limit ?? 10);
  },
});

export const getRecentReplaysWithDetails = query({
  args: { limit: v.optional(v.number()) },
  handler: async (ctx, { limit }) => {
    const replays = await ctx.db
      .query("replays")
      .order("desc")
      .take(limit ?? 10);
    
    // For each replay, fetch the related game and user records in parallel.
    // This is Convex's pattern for relational data — Promise.all keeps it
    // efficient by firing all lookups concurrently rather than one at a time.
    const withDetails = await Promise.all(
      replays.map(async (replay) => {
        const game = replay.gameId ? await ctx.db.get(replay.gameId) : null;
        const user = replay.userId ? await ctx.db.get(replay.userId) : null;

        return {
          ...replay,
          game,
          user,
        };
      })
    );

    return withDetails;
  },
});

export const getTopReplays = query({
  args: { limit: v.optional(v.number()) },
  handler: async (ctx, { limit }) => {
    // Fetch all replays, then look up each game's score for sorting.
    // For large datasets you'd want a denormalized score field on the replay
    // itself, but at this scale this approach is simple and readable.
    const replays = await ctx.db.query("replays").collect();

    const withScores = await Promise.all(
      replays.map(async (replay) => {
        const game = await ctx.db.get(replay.gameId);
        return {
          ...replay,
          game,
          score: game?.score ?? 0,
        };
      })
    );

    const sorted = withScores.sort((a, b) => b.score - a.score);

    return limit ? sorted.slice(0, limit) : sorted;
  },
});

Now create convex/leaderboards.ts. A leaderboard entry is a denormalized snapshot — a point-in-time record of one game result. We don't update entries in place; every finished game creates a new row. That keeps writes simple and makes querying the historical record straightforward.

import { query, mutation } from "./_generated/server";
import { v } from "convex/values";

export const insertScore = mutation({
  args: {
    userId: v.id("users"),
    score: v.number(),
    level: v.number(),
    linesCleared: v.number(),
  },
  handler: async (ctx, { userId, score, level, linesCleared }) => {
    const now = Date.now();
    return await ctx.db.insert("leaderboards", {
      userId,
      score,
      level,
      linesCleared,
    });
  },
});

export const getEntry = query({
  args: { entryId: v.id("leaderboards") },
  handler: async (ctx, { entryId }) => {
    return await ctx.db.get(entryId);
  },
});

export const listTop = query({
  args: { limit: v.optional(v.number()) },
  handler: async (ctx, { limit }) => {
    // Convex doesn't yet support ORDER BY DESC on indexed queries, so we fetch
    // all entries and sort in application code. For very large tables you'd
    // want to cap the initial query, but for a game leaderboard this is fine.
    const all = await ctx.db.query("leaderboards").withIndex("by_score").collect();
    const sorted = (all as any[]).sort((a, b) => b.score - a.score);
    if (limit) return sorted.slice(0, limit);
    return sorted;
  },
});

export const listByUser = query({
  args: { userId: v.id("users") },
  handler: async (ctx, { userId }) => {
    return await ctx.db.query("leaderboards").filter((q) => q.eq(q.field("userId"), userId)).collect();
  },
});

export const patchEntry = mutation({
  args: {
    entryId: v.id("leaderboards"),
    score: v.optional(v.number()),
    level: v.optional(v.number()),
    linesCleared: v.optional(v.number()),
  },
  handler: async (ctx, { entryId, score, level, linesCleared }) => {
    const patch: Record = {};
    if (score !== undefined) patch.score = score;
    if (level !== undefined) patch.level = level;
    if (linesCleared !== undefined) patch.linesCleared = linesCleared;
    return await ctx.db.patch(entryId, patch);
  },
});

export const deleteEntry = mutation({
  args: { entryId: v.id("leaderboards") },
  handler: async (ctx, { entryId }) => {
    return await ctx.db.delete(entryId);
  },
});

export const pruneOldEntries = mutation({
  args: { maxAgeMs: v.number() },
  handler: async (ctx, { maxAgeMs }) => {
    const cutoff = Date.now() - maxAgeMs;
    const all = await ctx.db.query("leaderboards").collect();
    // Delete entries whose _creationTime falls before the cutoff
    const toDelete = (all as any[]).filter((e) => (e._creationTime || 0) < cutoff);
    for (const e of toDelete) await ctx.db.delete(e._id);
    return toDelete.length;
  },
});

Understanding Convex Reactivity

Create a quick test in app/page.tsx to see real-time updates in action:

"use client";
import { useQuery } from "convex/react";
import { api } from "@/convex/_generated/api";

export default function Home() {
  const leaderboard = useQuery(api.leaderboards.getTop, { limit: 5 });

  return (
    
      {leaderboard?.map((entry, idx) => (
        
          #{idx + 1} {entry.userName} — {entry.score.toLocaleString()}
        
      ))}
    
  );
}

Open this page in two browser windows. When you add a new score via the Convex dashboard, both windows update within 50ms without any polling code. This is how your leaderboard will work in production.

When you call useQuery, Convex executes the query function on the server, returns the current results to your component, and automatically subscribes the client to any future changes in the tables that query touched.

When a mutation writes to one of those tables, Convex re-runs the query, diffs the results against what the client already has, and pushes only what changed. You write zero synchronization code — the subscription is established automatically and cleaned up when the component unmounts.

Building the Tetris Game Engine

The game engine lives entirely in components/tetris/GameBoard.tsx. This section walks through every part of it: constants, utility functions, state management, the game loop, and MCP integration.

Constants and Piece Definitions

const WIDTH = 10;
const HEIGHT = 20;

const PIECES: Record = {
  I: [[1, 1, 1, 1]],
  O: [[1, 1], [1, 1]],
  T: [[0, 1, 0], [1, 1, 1]],
  S: [[0, 1, 1], [1, 1, 0]],
  Z: [[1, 1, 0], [0, 1, 1]],
  J: [[1, 0, 0], [1, 1, 1]],
  L: [[0, 0, 1], [1, 1, 1]],
};

const PIECE_COLORS: Record = {
  I: "#00f0f0",
  O: "#f0f000",
  T: "#a000f0",
  S: "#00f000",
  Z: "#f00000",
  J: "#0000f0",
  L: "#f0a000",
};

const PIECE_TYPES = Object.keys(PIECES);

Each piece is stored as the smallest bounding box containing its shape, where 1 is a filled cell and 0 is transparent. This keeps rotation math simple and collision detection fast. The colors follow The Tetris Company's official guidelines, making the game instantly recognizable.

Core Utility Functions

These three functions are used throughout the engine. They are separated here because each one is independently testable and reused in multiple places.

Empty board

function emptyBoard() {
  return Array.from({ length: HEIGHT }, () =>
    Array.from({ length: WIDTH }, () => 0)
  );
}

Rotation (90 degrees clockwise)

function rotate(shape: number[][]) {
  const h = shape.length;
  const w = shape[0].length;
  const out = Array.from({ length: w }, () =>
    Array.from({ length: h }, () => 0)
  );
  for (let r = 0; r < h; r++) {
    for (let c = 0; c < w; c++) {
      out[c][h - 1 - r] = shape[r][c];
    }
  }
  return out;
}

The transformation out[c][h - 1 - r] = shape[r][c] transposes the matrix and reverses rows in one pass. For the T-piece, [0,1,0] / [1,1,1] becomes [1,0] / [1,1] / [1,0].

Collision detection

The most critical function, runs up to 60 times per second:

function canPlace(board: number[][], shape: number[][], x: number, y: number) {
  for (let r = 0; r < shape.length; r++) {
    for (let c = 0; c < shape[0].length; c++) {
      if (!shape[r][c]) continue;          // Skip empty cells immediately
      const br = y + r;
      const bc = x + c;
      if (bc < 0 || bc >= WIDTH || br < 0 || br >= HEIGHT) return false;
      if (board[br][bc]) return false;
    }
  }
  return true;
}

The early continue on empty cells is the key optimization. Most cells in a piece's bounding box are empty, so this skips the majority of iterations.

React State Management

export default function GameBoard() {
  const [board, setBoard] = useState(emptyBoard());
  const [current, setCurrent] = useState<{
    type: string; shape: number[][]; x: number; y: number;
  } | null>(null);
  const [next, setNext] = useState(
    () => PIECE_TYPES[Math.floor(Math.random() * PIECE_TYPES.length)]
  );
  const [running, setRunning] = useState(false);
  const [score, setScore] = useState(0);
  const [lines, setLines] = useState(0);
  const [level, setLevel] = useState(1);
  const [musicEnabled, setMusicEnabled] = useState(true);
  const [clearingRows, setClearingRows] = useState([]);

  // Refs for values that shouldn't trigger re-renders
  const actionsRef = useRef([]);
  const tickRef = useRef(null);
  const bgMusicRef = useRef(null);
  const clearSoundRef = useRef(null);

  // MCP integration hooks from Vercel template
  const callTool = useCallTool();
  const sendMessage = useSendMessage();
  const [gameId, setGameId] = useState | null>(null);
  const startTimeRef = useRef(null);
}

The distinction between useState and useRef matters for performance. actionsRef grows with every keypress and if it were state, every move would trigger a re-render and cause lag. tickRef holds the interval ID, which only needs to exist for cleanup. bgMusicRef holds an Audio element that never appears in the UI. None of these need to cause re-renders, so all three are refs.

Audio System

useEffect(() => {
  bgMusicRef.current = new Audio(
    "https://cdn.freesound.org/previews/612/612091_3283808-lq.mp3"
  );
  bgMusicRef.current.loop = true;
  bgMusicRef.current.volume = 0.3;

  clearSoundRef.current = new Audio(
    "https://cdn.freesound.org/previews/341/341695_5858296-lq.mp3"
  );
  clearSoundRef.current.volume = 0.5;

  return () => {
    bgMusicRef.current?.pause();
    bgMusicRef.current = null;
    clearSoundRef.current = null;
  };
}, []);

useEffect(() => {
  if (running && musicEnabled && bgMusicRef.current?.paused) {
    bgMusicRef.current.currentTime = 0;
    bgMusicRef.current.play().catch((e) => console.log("Music play failed:", e));
  } else if (!running || !musicEnabled) {
    bgMusicRef.current?.pause();
  }
}, [running, musicEnabled]);

The .catch() on .play() is essential. Browsers block autoplay audio until the user has interacted with the page and without it, you'd get uncaught promise rejections on every game start.

Game Loop

useEffect(() => {
  if (running) {
    const interval = Math.max(200, 1000 - (level - 1) * 100);
    tickRef.current = window.setInterval(() => {
      if (current) move(0, 1);
    }, interval);
    return () => { if (tickRef.current) clearInterval(tickRef.current); };
  } else {
    if (tickRef.current) clearInterval(tickRef.current);
  }
}, [running, current, level]);

The gravity speed formula produces this curve:

Level 1:  1000ms per drop  (relaxed)
Level 5:   600ms per drop
Level 10:  200ms per drop  (capped, very fast)

The dependency array includes current because the interval's callback closes over it. When a new piece spawns, current changes, the effect re-runs, and the interval restarts with the correct piece reference. Without this, the interval would hold a stale closure and pieces would behave incorrectly.

Keyboard Controls

useEffect(() => {
  const handler = (e: KeyboardEvent) => {
    if (!running) return;
    if (e.key === "ArrowLeft")  { e.preventDefault(); move(-1, 0, "L"); }
    if (e.key === "ArrowRight") { e.preventDefault(); move(1, 0, "R"); }
    if (e.key === "ArrowDown")  { e.preventDefault(); move(0, 1, "D"); }
    if (e.key === " " || e.key === "ArrowUp") {
      e.preventDefault();
      rotateCurrent("ROT");
    }
  };
  window.addEventListener("keydown", handler);
  return () => window.removeEventListener("keydown", handler);
}, [running, current]);

e.preventDefault() on arrow keys prevents the browser from scrolling the page while the game is active.

Piece Spawning

function spawnNext(boardParam?: number[][]) {
  const currentBoard = boardParam ?? board;
  const type = next;
  const shape = PIECES[type].map((r) => [...r]);  // Deep copy
  const x = Math.floor((WIDTH - shape[0].length) / 2);
  const y = 0;

  if (!canPlace(currentBoard, shape, x, y)) {
    finish();  // Top of board is blocked — game over
    return;
  }

  setCurrent({ type, shape, x, y });
  setNext(PIECE_TYPES[Math.floor(Math.random() * PIECE_TYPES.length)]);
}

The boardParam parameter exists because of a React state timing issue. After clearing lines, setBoard(newBoard) schedules a state update, but the next render hasn't happened yet. If you called spawnNext() without the parameter, it would read the stale board state and spawn the piece on the old board. Passing newBoard directly bypasses this:

setTimeout(() => {
  setBoard(newBoard);
  setCurrent(null);
  setClearingRows([]);
  setTimeout(() => spawnNext(newBoard), 50);  // Pass new board explicitly
}, 300);

Merging Piece with Board

function mergeCurrentToBoard(brd: number[][], cur: any) {
  const copy = brd.map((r) => [...r]);
  if (!cur) return copy;

  for (let r = 0; r < cur.shape.length; r++) {
    for (let c = 0; c < cur.shape[0].length; c++) {
      if (cur.shape[r][c]) {
        const rr = cur.y + r;
        const cc = cur.x + c;
        if (rr >= 0 && rr < HEIGHT && cc >= 0 && cc < WIDTH) {
          copy[rr][cc] = PIECE_TYPES.indexOf(cur.type) + 10;
        }
      }
    }
  }
  return copy;
}

The +10 offset encodes falling pieces differently from locked pieces:

0      = empty cell
1-7    = locked piece (I=1, O=2, T=3, ...)
10-16  = currently falling piece (I=10, O=11, T=12, ...)

This lets the renderer apply different styles to falling vs. locked pieces, so you could add opacity, glow, or borders to the active piece without touching locked cells.

Line Clearing

function clearLines(brd: number[][]) {
  let cleared = 0;
  const out: number[][] = [];

  for (let r = 0; r < HEIGHT; r++) {
    if (brd[r].every((v) => v !== 0)) {
      cleared++;
    } else {
      out.push(brd[r]);
    }
  }

  while (out.length < HEIGHT)
    out.unshift(Array.from({ length: WIDTH }, () => 0));

  return { board: out, cleared };
}

Full rows are filtered out, then empty rows are added at the top with unshift (not push), because gravity pulls pieces down, so new empty space must appear at the top.

The Movement Function

This is where collision detection, locking, line clearing, and spawning all connect:

function move(dx: number, dy: number, actionCode?: string) {
  if (!current) return;

  const nx = current.x + dx;
  const ny = current.y + dy;

  if (canPlace(board, current.shape, nx, ny)) {
    setCurrent({ ...current, x: nx, y: ny });
    if (actionCode) actionsRef.current.push({ t: Date.now(), a: actionCode });
  } else if (dy === 1) {
    // Downward move failed — piece has landed
    const merged = mergeCurrentToBoard(board, current);
    const normalized = merged.map((r) =>
      r.map((v) => (v >= 10 ? v - 9 : v))  // Convert falling values to locked
    );

    const { board: newBoard, cleared } = clearLines(normalized);

    if (cleared > 0) {
      // Play sound
      if (clearSoundRef.current && musicEnabled) {
        clearSoundRef.current.currentTime = 0;
        clearSoundRef.current.play().catch(console.log);
      }

      // Identify which rows flash
      const clearingRowIndices: number[] = [];
      for (let r = 0; r < HEIGHT; r++) {
        if (normalized[r].every((v) => v !== 0)) clearingRowIndices.push(r);
      }
      setClearingRows(clearingRowIndices);

      // Update score and level
      setScore((s) => s + cleared * 100);
      setLines((prev) => {
        const newLines = prev + cleared;
        setLevel(Math.floor(newLines / 10) + 1);
        return newLines;
      });

      // Animate, then update board
      setTimeout(() => {
        setBoard(newBoard);
        setCurrent(null);
        setClearingRows([]);
        setTimeout(() => spawnNext(newBoard), 50);
      }, 300);
    } else {
      setBoard(newBoard);
      setCurrent(null);
      setTimeout(() => spawnNext(newBoard), 50);
    }
  }
  // Horizontal collision: do nothing (piece stays in place)
}

Only dy === 1 failures trigger locking. A failed left or right move simply stops the piece; it doesn't land. The 300ms animation window gives players visual feedback before cleared rows disappear.

Rotation

function rotateCurrent(actionCode?: string) {
  if (!current) return;
  const newShape = rotate(current.shape);
  if (canPlace(board, newShape, current.x, current.y)) {
    setCurrent({ ...current, shape: newShape });
    if (actionCode) actionsRef.current.push({ t: Date.now(), a: actionCode });
  }
}

If the rotated shape doesn't fit at the current position, nothing happens. A full implementation would add wall kicks (trying x±1, y-1 offsets before giving up), but this simplified version covers the vast majority of cases.

Game Start and Finish

async function start() {
  const b = emptyBoard();
  setBoard(b);
  setScore(0); setLines(0); setLevel(1);
  actionsRef.current = [];
  actionsRef.current.push({ t: Date.now(), a: "START" });

  setRunning(true);
  startTimeRef.current = Date.now();

  // Create game record via MCP tool (non-blocking)
  (async () => {
    try {
      const toolRes = await callTool?.("start_game", {});
      const gameIdToUse = (toolRes as any)?.structuredContent?.gameId;
      if (gameIdToUse) setGameId(gameIdToUse);
    } catch (err) {
      console.error("Failed to create game record:", err);
    }
  })();

  setTimeout(() => spawnNext(b), 10);
}

The MCP tool call is wrapped in a self-invoking async function so it doesn't block the game from starting. The board resets and the first piece spawns immediately; the game ID arrives asynchronously and is stored for use when the game ends.

async function finish() {
  setRunning(false);

  const durationMs = startTimeRef.current
    ? Date.now() - startTimeRef.current
    : undefined;
  const replayActions = actionsRef.current.slice();

  if (gameId && callTool) {
    try {
      const result = await callTool("finish_game", {
        gameId, score, level,
        linesCleared: lines,
        replayActions,
        durationMs,
      });

      const message = (result as any)?.content?.[0]?.text
        || `Game finished! Score: \({score}, Level: \){level}, Lines: ${lines}`;

      await sendMessage?.(message);
    } catch (err) {
      // Graceful fallback — still show results even if save fails
      await sendMessage?.(
        `Game finished locally — Score: \({score}, Level: \){level} ` +
        `(Could not save: ${err instanceof Error ? err.message : String(err)})`
      );
    }
  } else {
    await sendMessage?.(
      `Game finished locally — Score: \({score}, Level: \){level} (No game ID)`
    );
  }

  // Reset all state
  setBoard(emptyBoard());
  setCurrent(null);
  setScore(0); setLines(0); setLevel(1);
  actionsRef.current = [];
  setGameId(null);
  startTimeRef.current = null;
}

The graceful degradation pattern is important: the game works even if the backend is unreachable. Players always see their score, and saving is a best-effort operation.

Board Rendering

const display = mergeCurrentToBoard(board, current);
const cellPx = Math.max(18, Math.min(32, Math.floor(360 / WIDTH)));

function getCellColor(value: number): string {
  if (value === 0) return "#0f172a";
  const typeIndex = value >= 10 ? value - 10 : value - 1;
  return PIECE_COLORS[PIECE_TYPES[typeIndex]];
}

return (
  
    {display.flatMap((row, r) =>
      row.map((cell, c) => {
        const isClearing = clearingRows.includes(r);
        return (
          
        );
      })
    )}
  
);

Cell size is clamped between 18px (readable on mobile) and 32px (comfortable on desktop), fitting a 360px container. The clearing animation fades rows to 50% opacity and scales them slightly larger, a subtle pulse effect before they disappear.

Control Buttons

These mirror the keyboard controls exactly, making the game fully playable on touch devices inside ChatGPT's iframe.

Replay Recording

Throughout the component, every player action is stamped and stored:

actionsRef.current.push({ t: Date.now(), a: actionCode });

A typical game produces a few hundred actions totaling less than 20KB of JSON. Because a ref is used instead of state, recording has zero rendering overhead. When the game ends, actionsRef.current.slice() takes a snapshot of the array and passes it to finish_game, where Convex stores it alongside the final score.

Implementing Kinde OAuth Authentication

Authentication in ChatGPT apps works differently from traditional web apps. ChatGPT is the OAuth client: it handles the redirect, code exchange, and token storage. Your app is the resource server. You receive tokens, validate them, and map OAuth identities to your database users.

OAuth Architecture Overview

Layer 1: OAuth Discovery
  /.well-known/oauth-protected-resource
  -> Tells ChatGPT where to authenticate

Layer 2: Token Extraction and Validation
  extractTokenFromArgs() -> Find token in MCP context
  validateKindeToken()   -> Verify signature with JWKS
  getKindeUserProfile()  -> Fetch user details from Kinde

Layer 3: User Mapping
  requireAuthForTool()   -> Protect MCP tools
  upsertLinkedAccount()  -> Create/update Convex user

OAuth Discovery Endpoint

You created this in Section 3. Here is the full implementation with proper fallbacks:

// app/mcp/.well-known/oauth-protected-resource/route.ts
import { NextResponse } from 'next/server';

const MCP_SERVER_URL =
  process.env.MCP_AUDIENCE ||
  process.env.MCP_SERVER_URL ||
  `https://${process.env.VERCEL_URL || 'localhost'}`;

const DEFAULT_KINDE_ISSUER = 'https://devrelstudio.kinde.com';
const KINDE_ISSUER_URL =
  process.env.KINDE_ISSUER_URL ||
  process.env.KINDE_ISSUER ||
  DEFAULT_KINDE_ISSUER;

export async function GET() {
  const authServers = [KINDE_ISSUER_URL];
  console.log('oauth-protected-resource using authorization_servers:', authServers);

  return NextResponse.json({
    resource: MCP_SERVER_URL,
    authorization_servers: authServers,
    scopes_supported: ['openid', 'profile', 'email'],
    bearer_methods_supported: ['header'],
    resource_documentation: `${MCP_SERVER_URL}/docs`,
  });
}

When ChatGPT encounters a tool requiring authentication, it GETs this endpoint, reads authorization_servers, and redirects the user to Kinde. Without this endpoint, ChatGPT cannot discover your OAuth configuration and the entire auth flow breaks silently.

Token Validation

Update app/lib/kinde.ts with production-ready validation:

import { createRemoteJWKSet, jwtVerify } from 'jose';

const KINDE_ISSUER_URL = process.env.KINDE_ISSUER_URL || process.env.KINDE_ISSUER;
const MCP_AUDIENCE =
  process.env.MCP_AUDIENCE ||
  process.env.MCP_SERVER_URL ||
  process.env.NEXT_PUBLIC_MCP_AUDIENCE;

// getJwks is extracted into its own function so that createRemoteJWKSet is
// called once and reused across requests. createRemoteJWKSet handles HTTP
// caching internally, meaning Kinde's public keys are only fetched when the
// cache expires, not on every token validation. Creating a new instance per
// request would bypass this and add unnecessary latency.
function getJwks() {
  if (!KINDE_ISSUER_URL) {
    throw new Error('KINDE_ISSUER_URL (or KINDE_ISSUER) environment variable is not set');
  }
  return createRemoteJWKSet(new URL(`${KINDE_ISSUER_URL}/.well-known/jwks`));
}

export async function validateKindeToken(token: string) {
  if (!token) throw new Error('No token provided');
  if (!KINDE_ISSUER_URL) throw new Error('KINDE_ISSUER_URL not configured');
  if (!MCP_AUDIENCE) throw new Error('MCP_AUDIENCE (or MCP_SERVER_URL) not configured');

  const JWKS = getJwks();

  // jwtVerify does several things in one call:
  // 1. Decodes the JWT header and payload
  // 2. Fetches Kinde's public keys from the JWKS endpoint (using cached keys when available)
  // 3. Finds the matching key using the token's `kid` header field
  // 4. Verifies the cryptographic signature
  // 5. Checks that `iss` matches your Kinde domain and `aud` matches your MCP URL
  //
  // If the token was tampered with, expired, or issued by a different service,
  // jwtVerify throws and your handler never runs.
  const { payload } = await jwtVerify(token, JWKS, {
    issuer: KINDE_ISSUER_URL,
    audience: MCP_AUDIENCE,
  } as any);

  return payload as Record;
}

export async function getKindeUserProfile(token: string) {
  if (!token) throw new Error('No token provided');
  if (!KINDE_ISSUER_URL) throw new Error('KINDE_ISSUER_URL not configured');

  const url = `${KINDE_ISSUER_URL}/oauth2/v2/user_profile`;
  const res = await fetch(url, {
    headers: { Authorization: `Bearer ${token}`, Accept: 'application/json' },
  });

  if (!res.ok) {
    const txt = await res.text();
    throw new Error(`Failed to fetch user profile: \({res.status} \){txt}`);
  }

  return (await res.json()) as Record;
}

The JWKS endpoint (/.well-known/jwks) returns Kinde's current public keys:

{
  "keys": [
    { "kty": "RSA", "use": "sig", "kid": "abc123", "n": "0vx7...", "e": "AQAB" }
  ]
}

Kinde signs tokens with its private key and you verify with the matching public key. Even if an attacker intercepts a token, they cannot forge new ones without the private key.

Token Extraction from MCP Context

Before looking at the code, it is worth understanding why token extraction needs this much logic. The MCP protocol does not mandate a single canonical location for the Bearer token. Depending on the ChatGPT version, MCP transport (HTTP vs SSE), and how the SDK processes the request, the token can arrive in several different places: nested in the MCP context object under requestInfo.headers, on a raw Request object, flattened directly on context.headers, or not forwarded into the context at all because it was pre-registered against a request ID in an earlier middleware step.

The function below tries every known location in priority order, from most reliable to least, so your tool handlers work regardless of exactly how the token arrives.

Create app/lib/mcpAuth.ts:

import { getLastAuthToken } from './mcpRequestState';

export async function extractTokenFromArgs(args: any, context?: any) {
  // Strategy 1: context.requestInfo.headers
  // The most common location in MCP v1.0+ over HTTP. The header name may be
  // lowercase or Title-Case depending on which HTTP layer normalized it.
  if (context?.requestInfo?.headers) {
    const authHeader =
      context.requestInfo.headers.authorization ||
      context.requestInfo.headers.Authorization;
    if (authHeader?.startsWith('Bearer ')) {
      return authHeader.substring(7);
    }
  }

  // Strategy 2: context.request.headers
  // Used when the MCP handler passes a raw Fetch API Request object through
  // the context. Headers here are accessed with .get(), not dot notation.
  if (context?.request?.headers) {
    const authHeader =
      context.request.headers.get?.('Authorization') ||
      context.request.headers.get?.('authorization');
    if (authHeader?.startsWith('Bearer ')) return authHeader.substring(7);
  }

  // Strategy 3: context.headers directly
  // Some MCP transports flatten headers onto the context object itself.
  // We try both the Fetch API .get() method and plain property access to
  // cover both cases.
  if (context?.headers) {
    const authHeader =
      context.headers.get?.('Authorization') ||
      context.headers.get?.('authorization') ||
      context.headers.Authorization ||
      context.headers.authorization;
    if (authHeader && typeof authHeader === 'string' && authHeader.startsWith('Bearer ')) {
      return authHeader.substring(7);
    }
  }

  // Strategy 4: Request ID mapping
  // In some SSE-based transports, the Authorization header cannot be forwarded
  // through the MCP context. The POST handler middleware (see the POST export in
  // mcp/route.ts) pre-registers the token against every request ID found in the
  // body. Here we check whether any of the IDs in this context have a match.
  const possibleIds = [
    context?.requestId,
    context?.requestInfo?.requestId,
    context?.requestInfo?.id,
    context?.id,
    context?.sessionId,
    context?.requestInfo?.sessionId,
  ].filter(Boolean);

  for (const id of possibleIds) {
    const token = (await import('./mcpRequestMap')).getTokenForRequestId(id);
    if (token) return token;
  }

  // Strategy 5: Last known token (single-user fallback)
  // If all strategies above fail, return the most recently seen token for this
  // server process. This is safe in local development where only one user is
  // active, but should NOT be relied upon in a multi-user production deployment
  // where requests can interleave.
  const last = getLastAuthToken();
  if (last) return last;

  return null;
}

The two supporting files that Strategies 4 and 5 depend on are in-memory maps that live for the duration of the server process:

// app/lib/mcpRequestMap.ts
// Maps MCP request IDs to the Bearer token that arrived with them.
// Entries are written by the POST handler middleware before the MCP handler
// runs, ensuring the token is findable even after the original Request object
// is gone.
const tokenMap = new Map();

export function setTokenForRequestId(id: string, token: string) {
  tokenMap.set(id, token);
}

export function getTokenForRequestId(id: string): string | null {
  return tokenMap.get(id) ?? null;
}

export function clearTokenForRequestId(id: string) {
  tokenMap.delete(id);
}

export function clearAll() {
  tokenMap.clear();
}

// app/lib/mcpRequestState.ts
// Tracks the most recently seen token as a last-resort fallback.
// Only appropriate for single-user or development scenarios.
let lastAuthToken: string | null = null;

export function setLastAuthToken(token: string | null) {
  lastAuthToken = token;
}

export function getLastAuthToken() {
  return lastAuthToken;
}

Requiring Auth in MCP Tools

With token extraction handled, you can now write requireAuthForTool: the single function you call at the top of any protected tool handler. It extracts the token, validates it against Kinde's JWKS endpoint, and returns either the authenticated user's profile or a structured MCP error response that ChatGPT knows how to act on.

// app/lib/mcpAuth.ts (continued)
import { validateKindeToken, getKindeUserProfile } from './kinde';

const MCP_SERVER_URL =
  process.env.MCP_SERVER_URL ||
  process.env.MCP_AUDIENCE ||
  `https://${process.env.VERCEL_URL || 'localhost'}`;

// Builds the WWW-Authenticate challenge value pointing to your OAuth discovery
// endpoint. ChatGPT reads this value and uses it to initiate the Kinde login
// flow for the user.
export function makeAuthenticateMeta(message = 'Sign in required') {
  return [
    `Bearer resource_metadata="${MCP_SERVER_URL}/mcp/.well-known/oauth-protected-resource", ` +
    `error="insufficient_scope", error_description="${message}"`,
  ];
}

export async function requireAuthForTool(args: any, context?: any) {
  const token = await extractTokenFromArgs(args, context);

  if (!token) {
    // No token found anywhere. Return an MCP error with the WWW-Authenticate
    // challenge. ChatGPT reads the mcp/www_authenticate metadata field, fetches
    // your discovery endpoint, and redirects the user to Kinde to sign in.
    return {
      isError: true,
      content: [{ type: 'text', text: 'Please sign in to continue.' }],
      _meta: { 'mcp/www_authenticate': makeAuthenticateMeta() },
    };
  }

  try {
    const payload = await validateKindeToken(token).catch(() => null);
    const profile = await getKindeUserProfile(token).catch(() => null);

    if (!payload) {
      // Token arrived but failed cryptographic validation. Likely expired or tampered.
      return {
        isError: true,
        content: [{ type: 'text', text: 'Invalid token. Please sign in again.' }],
        _meta: { 'mcp/www_authenticate': makeAuthenticateMeta('Invalid token') },
      };
    }

    // Both checks passed. Return the validated identity to the caller.
    return { ok: true, token, profile, payload };
  } catch (err: any) {
    return {
      isError: true,
      content: [{ type: 'text', text: 'Authentication failed. Please sign in again.' }],
      _meta: { 'mcp/www_authenticate': makeAuthenticateMeta('Authentication failed') },
    };
  }
}

The _meta['mcp/www_authenticate'] field follows RFC 6750 (Bearer Token Usage). When ChatGPT receives a tool response containing this field, it treats the response as an authentication challenge: it fetches your discovery endpoint, reads authorization_servers, redirects the user to Kinde, and re-calls the tool with the resulting token.

Your tool handler never needs to know whether a call was an initial attempt or a post-authentication retry. It calls requireAuthForTool at the top and proceeds if ok is true:

async (args, context) => {
  const auth = await requireAuthForTool(args, context);

  if ((auth as any).isError) {
    return auth; // Returns the auth challenge to ChatGPT
  }

  const { profile, payload } = auth as any;
  // User is authenticated — proceed with tool logic
}

Linking OAuth Identities to Convex Users

When a user authenticates, you map their Kinde identity to a Convex user. The upsertLinkedAccount mutation from Section 4 handles this. In your MCP tool handlers, call it like this:

const linkedUserId = await callConvexMutation(
  api.users.upsertLinkedAccount,
  {
    provider: 'kinde',
    providerUserId: String(payload.sub),  // e.g. "kinde|2151678548"
    email: profile?.email,
    displayName:
      `\({profile?.given_name || ''} \){profile?.family_name || ''}`.trim() ||
      profile?.email ||
      'Anonymous',
    avatarUrl: profile?.picture,
  }
);

const userId = String(linkedUserId);

The flow is: Kinde JWT arrives with sub: "kinde|2151678548" -> check linkedAccounts for that provider/subject pair -> if found, return the existing userId and update lastSeenAt -> if not found, create a new user and linked account -> return the new userId.

This means a player authenticating for the first time gets a new Convex user created automatically. The same player returning gets their existing account, preserving all their scores and replays.

Token Extraction in the POST Handler

The strategies in extractTokenFromArgs handle finding a token once the MCP handler is already running. But some transports consume the request body before the handler sees it, meaning the token in the Authorization header has no corresponding context to land in. This middleware solves that by reading the token and the request IDs from the raw body before the handler runs, storing each pairing in mcpRequestMap so Strategy 4 can find them later.

Add this to mcp/route.ts before the handler export:

export async function POST(req: Request) {
  let clonedReq = req;

  try {
    const authHeader =
      req.headers.get('Authorization') || req.headers.get('authorization');

    if (authHeader && typeof authHeader === 'string' && authHeader.startsWith('Bearer ')) {
      const token = authHeader.substring(7);
      const bodyText = await req.text();

      if (bodyText) {
        let parsed: any = null;
        try {
          parsed = JSON.parse(bodyText);
        } catch (e) {
          // Body is not JSON — skip ID collection
        }

        const idsToCheck: string[] = [];

        // collectIds walks the parsed body recursively because request IDs can
        // appear at different nesting depths depending on the MCP transport and
        // the JSON-RPC batch format. A shallow check would miss IDs nested inside
        // params or method objects.
        function collectIds(obj: any) {
          if (!obj || typeof obj !== 'object') return;
          for (const k of Object.keys(obj)) {
            if (k === 'requestId' || k === 'sessionId' || k === 'request_id' || k === 'id') {
              const v = obj[k];
              if (typeof v === 'string') idsToCheck.push(v);
            } else if (typeof obj[k] === 'object') {
              collectIds(obj[k]);
            }
          }
        }

        collectIds(parsed);

        for (const id of idsToCheck) {
          setTokenForRequestId(id, token);
        }

        // The request body can only be read once. Clone the request with the
        // already-read body text so the MCP handler can read it again normally.
        clonedReq = new Request(req.url, {
          method: req.method,
          headers: req.headers,
          body: bodyText,
        });
      }
    }

    return await handler(clonedReq);
  } catch (error) {
    throw error;
  }
}

Validation Endpoint for Debugging

Create app/api/mcp/validate-token/route.ts to test token validation manually during development:

import { NextResponse } from 'next/server';
import { validateKindeToken, getKindeUserProfile } from '@/app/lib/kinde';

export async function POST(req: Request) {
  try {
    const authHeader = req.headers.get('authorization') || '';
    const tokenFromHeader = authHeader.startsWith('Bearer ')
      ? authHeader.replace('Bearer ', '')
      : undefined;
    const body = await req.json().catch(() => ({}));
    const token = tokenFromHeader || body.token;

    if (!token) {
      return NextResponse.json({ error: 'No token provided' }, { status: 401 });
    }

    const payload = await validateKindeToken(token);

    let profile = null;
    try {
      profile = await getKindeUserProfile(token);
    } catch (e) {
      // Non-fatal. The payload alone is enough to confirm the token is valid.
    }

    return NextResponse.json({ ok: true, payload, profile });
  } catch (err: any) {
    return NextResponse.json({ error: err?.message ?? String(err) }, { status: 401 });
  }
}

Test it with a token obtained from Kinde's OAuth Playground or a manual authorization flow:

curl -X POST http://localhost:3000/api/mcp/validate-token \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
  -H "Content-Type: application/json"

# Success:
# { "ok": true, "payload": { "sub": "kinde|...", "email": "..." }, "profile": {...} }

# Expired token:
# { "error": "Token has expired" }

Security Checklist

Before shipping, verify these practices are in place:

Server-side validation only. Never trust user-provided identity claims. Always call validateKindeToken on the server.
Verify both issuer and audience. Without audience checking, a token issued for a different app would pass validation.
JWKS caching. createRemoteJWKSet handles HTTP caching internally. Do not create a new instance per request.
Fail fast on missing config. Throw at startup if KINDE_ISSUER_URL or MCP_AUDIENCE are missing rather than failing silently on the first real request.
Graceful error responses. Return isError: true with a user-friendly message rather than exposing stack traces or token details.

Building the MCP Integration

The MCP route is the core of your ChatGPT integration. It registers tools, handles authentication, calls Convex, and returns widgets. Everything from Sections 3 through 6 comes together here.

Convex HTTP Client

MCP tool handlers run in Next.js server context, not React. You cannot use useQuery or useMutation. Instead, use the Convex HTTP client directly. Create app/lib/convex.ts:

import { ConvexHttpClient } from "convex/browser";

// Singleton: ConvexHttpClient maintains a connection pool internally.
// Creating a new instance per request wastes those connections and
// adds latency to cold starts. One client shared across all requests
// is the correct pattern.
let client: ConvexHttpClient | null = null;

export function getConvexClient() {
  if (!client) {
    const url = process.env.NEXT_PUBLIC_CONVEX_URL;
    if (!url) throw new Error("NEXT_PUBLIC_CONVEX_URL is not set");
    client = new ConvexHttpClient(url);
  }
  return client;
}

export async function callConvexMutation(
  fn: any,
  args: Record
): Promise {
  return getConvexClient().mutation(fn, args) as Promise;
}

export async function callConvexQuery(
  fn: any,
  args: Record
): Promise {
  return getConvexClient().query(fn, args) as Promise;
}

Before registering tools, you need a helper to render widget HTML. The imports below pull in everything the MCP route depends on. zodToJsonSchema is included here because the MCP SDK expects tool input schemas in JSON Schema format, not Zod format. zodToJsonSchema converts your Zod definitions at registration time so you get Zod's type safety when writing schemas and valid JSON Schema in the manifest ChatGPT reads.

import {
  createMcpHandler,
  experimental_withMcpAuth,
  getAppsSdkCompatibleHtml,
} from "mcp-handler";
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { z } from "zod";
import { zodToJsonSchema } from "zod-to-json-schema";
import { api } from "@/convex/_generated/api";
import { Id } from "@/convex/_generated/dataModel";
import { callConvexMutation, callConvexQuery } from "@/app/lib/convex";
import {
  extractTokenFromArgs,
  requireAuthForTool,
  setTokenForRequestId,
} from "@/app/lib/mcpAuth";
import { setLastAuthToken } from "@/app/lib/mcpRequestState";
import { baseURL } from "@/lib/baseURL";

// getAppsSdkCompatibleHtml wraps a URL in the HTML structure ChatGPT expects
// for interactive widgets. It sets the MIME type to text/html+skybridge, which
// tells ChatGPT to render the response as a sandboxed iframe rather than
// displaying it as plain text.
function makeWidgetHtml(path: string, params: Record = {}) {
  const url = new URL(path, baseURL);
  Object.entries(params).forEach(([k, v]) => url.searchParams.set(k, v));
  return getAppsSdkCompatibleHtml(url.toString());
}

MCP Server Setup

const server = new Server(
  { name: "tetris-server", version: "1.0.0" },
  { capabilities: { tools: {} } }
);

Tool Registration: `start_game`

server.registerTool(
  "start_game",
  {
    description:
      "Start a new Tetris game. Returns an interactive widget for the user to play. " +
      "Authentication is optional — anonymous users can play but won't appear on the leaderboard.",
    inputSchema: zodToJsonSchema(
      z.object({
        public: z.boolean().optional()
          .describe("Whether to show this game on the leaderboard. Default false."),
        seed: z.number().optional()
          .describe("Random seed for reproducible piece sequences."),
      })
    ),
    // Two security schemes implement OR logic: ChatGPT calls this tool with
    // whatever auth state it currently has. If the user is signed in, the token
    // arrives and we link a Convex user. If not, the game starts anonymously.
    // A single scheme would make authentication required and block anonymous play.
    securitySchemes: [
      { type: "noauth" },
      { type: "oauth2", scopes: ["openid", "profile", "email"] },
    ],
  },
  async (args: any, context?: any) => {
    let userId: string | undefined;

    // Attempt auth but don't require it
    const token = await extractTokenFromArgs(args, context);
    if (token) {
      try {
        const authResult = await requireAuthForTool(args, context);
        if (!(authResult as any).isError) {
          const { profile, payload } = authResult as any;
          const linkedId = await callConvexMutation(
            api.users.upsertLinkedAccount,
            {
              provider: "kinde",
              providerUserId: String(payload.sub),
              email: profile?.email,
              displayName:
                `\({profile?.given_name || ""} \){profile?.family_name || ""}`.trim() ||
                profile?.email ||
                "Anonymous",
              avatarUrl: profile?.picture,
            }
          );
          userId = String(linkedId);
        }
      } catch (err) {
        console.error("[start_game] Auth error (proceeding anonymously):", err);
      }
    }

    const gameId = await callConvexMutation(api.games.createGame, {
      userId: userId ? (userId as Id<"users">) : undefined,
      public: args.public ?? false,
      seed: args.seed,
    });

    const widget = makeWidgetHtml("/tetris/play", {
      gameId: String(gameId),
    });

    return {
      content: [{ type: "text", text: widget }],
      // structuredContent is returned alongside the widget HTML so that
      // GameBoard.tsx can extract the gameId from the callTool response
      // without parsing the HTML. See the start() function in GameBoard.tsx.
      structuredContent: { gameId: String(gameId) },
    };
  }
);

Tool Registration: `finish_game`

server.registerTool(
  "finish_game",
  {
    description:
      "Record the final score for a completed Tetris game and save the replay. " +
      "Call this when the player's game ends.",
    inputSchema: zodToJsonSchema(
      z.object({
        gameId: z.string().describe("The game ID returned by start_game."),
        score: z.number().describe("Final score."),
        level: z.number().describe("Level reached."),
        linesCleared: z.number().describe("Total lines cleared."),
        replayActions: z
          .array(
            z.object({
              t: z.number().describe("Milliseconds since game start."),
              a: z.string().describe("Action code: L, R, D, ROT, HD, START."),
              d: z.any().optional(),
            })
          )
          .optional()
          .describe("Compact action log for replay playback."),
        durationMs: z.number().optional().describe("Total game duration in ms."),
      })
    ),
    securitySchemes: [
      { type: "noauth" },
      { type: "oauth2", scopes: ["openid", "profile", "email"] },
    ],
  },
  async (args: any, context?: any) => {
    try {
      const result = await callConvexMutation(api.games.finishGame, {
        gameId: args.gameId as Id<"games">,
        // Number() coercion is defensive: ChatGPT's LLM occasionally serializes
        // numeric values as strings when constructing tool arguments. Coercing
        // explicitly here prevents type errors in the Convex mutation.
        score: Number(args.score),
        level: Number(args.level),
        linesCleared: Number(args.linesCleared),
        replayActions: args.replayActions ?? [],
        durationMs: args.durationMs ?? 0,
      });

      const score = Number(args.score);
      const lines = Number(args.linesCleared);
      const level = Number(args.level);

      const summary =
        `Game over! Final score: ${score.toLocaleString()} | ` +
        `Level: \({level} | Lines cleared: \){lines}. ` +
        (args.gameId ? `Replay saved (ID: ${String(result?.replayId ?? "").slice(0, 8)}...). ` : "") +
        (score > 10000 ? "Excellent game!" : score > 5000 ? "Nice run!" : "Keep practicing!");

      return {
        content: [{ type: "text", text: summary }],
        structuredContent: result,
      };
    } catch (err: any) {
      // Graceful fallback: always return a readable message rather than
      // letting the error surface as a raw exception in ChatGPT's UI.
      return {
        content: [
          {
            type: "text",
            text: `Score recorded locally: \({args.score}. (Save failed: \){err?.message ?? String(err)})`,
          },
        ],
      };
    }
  }
);

Tool Registration: `get_leaderboard`

server.registerTool(
  "get_leaderboard",
  {
    description: "Get the current Tetris leaderboard widget showing top scores.",
    inputSchema: zodToJsonSchema(
      z.object({
        limit: z.number().optional()
          .describe("Number of entries to show. Default 10, max 25."),
      })
    ),
    // Read-only, public data. No auth needed and requiring it would add
    // unnecessary friction for a tool that reveals nothing sensitive.
    securitySchemes: [{ type: "noauth" }],
  },
  async (args: any, _context?: any) => {
    const limit = Math.min(Number(args.limit ?? 10), 25);

    try {
      const topScores = await callConvexQuery(api.leaderboards.getTop, { limit });

      const widget = makeWidgetHtml("/tetris/leaderboard", {
        limit: String(limit),
      });

      return {
        content: [{ type: "text", text: widget }],
        structuredContent: { topScores },
      };
    } catch (err: any) {
      return {
        content: [{ type: "text", text: `Failed to fetch leaderboard: ${err?.message}` }],
      };
    }
  }
);

Tool Registration: `view_replay`

server.registerTool(
  "view_replay",
  {
    description: "Watch a recorded Tetris game replay.",
    inputSchema: zodToJsonSchema(
      z.object({
        replayId: z.string().describe("The replay ID to watch."),
      })
    ),
    securitySchemes: [{ type: "noauth" }],
  },
  async (args: any, _context?: any) => {
    try {
      const replay = await callConvexQuery(api.replays.getReplay, {
        replayId: args.replayId as Id<"replays">,
      });

      if (!replay) {
        return { content: [{ type: "text", text: "Replay not found." }] };
      }

      const widget = makeWidgetHtml("/tetris/replay", {
        replayId: args.replayId,
      });

      return {
        content: [{ type: "text", text: widget }],
        structuredContent: {
          replayId: args.replayId,
          score: replay.finalScore,
          level: replay.finalLevel,
          duration: replay.durationMs,
        },
      };
    } catch (err: any) {
      return {
        content: [{ type: "text", text: `Failed to load replay: ${err?.message}` }],
      };
    }
  }
);

Wiring Up the Handler and Exports

With all four tools registered, the final step is exporting the route handler that Next.js calls for every incoming request. There is one problem to solve first: the Authorization header that ChatGPT sends with authenticated requests needs to reach your tool handlers, but by the time those handlers execute, the original Request object has already been consumed by the MCP SDK's request parsing. The header is gone.

The solution is a thin middleware layer inside the POST export. Before the request reaches the MCP handler, this middleware reads the Authorization header, walks the JSON body to find every ID field, and registers the token against each ID in mcpRequestMap. When extractTokenFromArgs runs inside your tool handler, Strategy 4 finds the token via the matching request ID.

const handler = createMcpHandler(server);

export async function POST(req: Request) {
  let clonedReq = req;

  try {
    const authHeader =
      req.headers.get("Authorization") || req.headers.get("authorization");

    if (authHeader?.startsWith("Bearer ")) {
      const token = authHeader.substring(7);

      // Store as the most recently seen token for the last-resort fallback
      // (Strategy 5 in extractTokenFromArgs)
      setLastAuthToken(token);

      // req.body is a ReadableStream that can only be consumed once.
      // We read it here, before the MCP handler sees it, so we can extract
      // request IDs. The request is then reconstructed below with the same
      // body text so the handler can read it normally.
      const bodyText = await req.text();

      if (bodyText) {
        let parsed: any = null;
        try { parsed = JSON.parse(bodyText); } catch (e) {}

        // Walk the parsed body recursively. Request IDs can appear at different
        // nesting depths depending on the MCP transport and JSON-RPC batch
        // format. A shallow check would miss IDs nested inside params objects.
        // We cast a wide net across all known ID field names because different
        // MCP versions use different conventions.
        function collectIds(obj: any) {
          if (!obj || typeof obj !== "object") return;
          for (const k of Object.keys(obj)) {
            if (["requestId", "sessionId", "request_id", "id"].includes(k)) {
              if (typeof obj[k] === "string") setTokenForRequestId(obj[k], token);
            } else if (typeof obj[k] === "object") {
              collectIds(obj[k]);
            }
          }
        }
        collectIds(parsed);

        // Reconstruct a fresh Request with the already-read body text.
        // Without this, the MCP handler receives a Request with an exhausted
        // body stream and fails to parse the incoming tool call.
        clonedReq = new Request(req.url, {
          method: req.method,
          headers: req.headers,
          body: bodyText,
        });
      }
    }

    return await handler(clonedReq);
  } catch (error) {
    throw error;
  }
}

// GET handles MCP capability discovery. When you register the connector in
// ChatGPT, it makes a GET request to your MCP endpoint to fetch the tool
// manifest: the list of available tools, their descriptions, and their
// input schemas. The same handler serves both purposes.
export const GET = handler;

MCP Documentation Endpoint

Create app/mcp-docs/page.tsx. This page is referenced in your environment variables and appears when users ask ChatGPT to explain your app's capabilities:

export default function McpDocsPage() {
  return (
    
      Tetris ChatGPT App — MCP Documentation
      Available Tools
      
        
          start_game — Starts a new Tetris game and returns a
          playable widget. Optional: public (leaderboard), seed{" "}
          (reproducible sequence).
        
        
          finish_game — Records the final score and saves the
          replay. Requires gameId, score,{" "}
          level, linesCleared.
        
        
          get_leaderboard — Returns the top scores widget.
          Optional: limit (default 10).
        
        
          view_replay — Renders a recorded game replay.
          Requires replayId.
        
      
      Authentication
      
        All tools support anonymous access. Signing in via Kinde enables leaderboard
        entries and replay attribution.
      
    
  );
}

Tool Design Principles

A few patterns from this implementation worth keeping in mind for any MCP tool you build.

Defensive argument coercion. Use Number(args.score) and String(args.gameId) rather than trusting the types ChatGPT sends. The LLM occasionally serializes numeric values as strings when constructing tool arguments, and a type mismatch in a Convex mutation will throw rather than coerce silently.

Structured content alongside widget HTML. Return structuredContent with key values even when the primary content is a widget. This lets GameBoard.tsx extract gameId directly from the callTool response and lets callers inspect results programmatically without parsing HTML.

Graceful degradation in every handler. Wrap Convex calls in try/catch and return a meaningful error message rather than throwing. ChatGPT surfaces unhandled tool errors poorly; a friendly fallback keeps the user experience smooth even when the backend is unreachable.

Minimal auth in read-only tools. For get_leaderboard and view_replay, skip auth entirely rather than attempting token extraction. These tools are read-only and public; adding auth would introduce friction and failure modes with no security benefit.

Verifying the MCP Route

Test the tool listing endpoint locally:

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Expected response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      { "name": "start_game", "description": "Start a new Tetris game...", "inputSchema": {...} },
      { "name": "finish_game", "description": "Record the final score...", "inputSchema": {...} },
      { "name": "get_leaderboard", "description": "Get the current Tetris leaderboard...", "inputSchema": {...} },
      { "name": "view_replay", "description": "Watch a recorded Tetris game replay.", "inputSchema": {...} }
    ]
  }
}

If you see all four tools, the MCP server is configured correctly. If you see an empty array, check that all server.registerTool calls come before createMcpHandler(server).

Building the Supporting Features

With the game engine and MCP integration complete, this section builds the pages users actually see: the landing page, game interface, leaderboard, and replay viewer.

Landing Page

Create app/page.tsx. The landing page does two things: it renders navigation cards to the three main features, and it reads any tool output passed by ChatGPT to personalise the greeting. useWidgetProps is a hook from the Vercel ChatGPT Apps SDK that gives you access to the structured output from the MCP tool that opened this widget. If the user is signed in and start_game returned a name field in its structuredContent, the greeting will address them by name rather than showing the default copy.

"use client";

import Link from "next/link";
import { useRouter } from "next/navigation";
import { Button } from "@/components/ui/button";
import { Card, CardHeader, CardTitle, CardDescription } from "@/components/ui/card";
import { Play, Film, Trophy } from "lucide-react";
import { useWidgetProps } from "./hooks";

export default function Home() {
  const router = useRouter();

  // useWidgetProps reads the structured output that the MCP tool passed when
  // it opened this widget. If start_game returned a name in structuredContent,
  // we use it here to personalise the greeting. If not, we fall back to the
  // default tagline.
  const toolOutput = useWidgetProps<{
    name?: string;
    result?: { structuredContent?: { name?: string } };
  }>();

  const name = toolOutput?.result?.structuredContent?.name || toolOutput?.name;

  return (
    
      
        
          Tetris
          
            {name
              ? `Hi ${name}, ready to play?`
              : "Play classic Tetris in your browser — save replays and climb the leaderboard."}
          
        

        
          
            
              
                
              
              Play
              Start a new Tetris game and save replays when you finish.
            
          

          
            
              
                
              
              Replays
              View recent replays and replay your best runs.
            
          

          
            
              
                
              
              Leaderboard
              See the top scores and compete for the highest rank.
            
          
        

        
          
            
              
            
            
              
            
            
              
            
          
        
      

      
        
          Play Tetris — save replays and compete on the leaderboard
        
      
    
  );
}

Game Page

Create app/tetris/play/page.tsx. This is a thin wrapper that mounts the GameBoard component. All game logic lives in the component itself; the page just provides the route and a heading.

"use client";

import React from "react";
import GameBoard from "@/components/tetris/GameBoard";

export default function PlayPage() {
  return (
    
      Play Tetris in ChatGPT
      
    
  );
}

Leaderboard Component

Create components/tetris/Leaderboard.tsx. Because Convex does not perform relational joins natively, this component uses two separate queries: one for the leaderboard entries and one to look up the user records for each entry. The results are joined client-side using a Map. Both queries are live subscriptions, so the table refreshes automatically for everyone viewing it the moment any player finishes a game.

"use client";

import React from 'react';
import { useQuery } from 'convex/react';
import { api } from '@/convex/_generated/api';

export default function Leaderboard() {
  const entries = useQuery(api.leaderboards.listTop, { limit: 20 }) || [];

  const userIds = entries.map((e: any) => e.userId).filter(Boolean);

  // "skip" is a Convex sentinel value that tells useQuery not to run the query
  // at all. Without it, passing an empty userIds array would fire a query that
  // returns nothing useful and produces a loading state on every initial render.
  const users = useQuery(
    api.users.getMultipleById,
    userIds.length > 0 ? { userIds } : "skip"
  );

  // Build a lookup map so each entry can find its user in O(1) rather than
  // scanning the users array on every render.
  const userMap = new Map();
  if (users) {
    users.forEach((user: any) => {
      if (user) userMap.set(user._id, user);
    });
  }

  return (
    
      Leaderboard
      
        {entries.map((e: any, idx: number) => {
          const user = userMap.get(e.userId);
          const displayName = user
            ? (user.displayName || `\({user.firstName || ''} \){user.lastName || ''}`.trim() || user.email)
            : 'Anonymous';

          return (
            
              {displayName}
              {e.score}
            
          );
        })}
      
    
  );
}

Leaderboard Page

Create app/tetris/leaderboard/page.tsx. This is a server component that mounts the Leaderboard component at the /tetris/leaderboard route.

import React from "react";
import Leaderboard from "@/components/tetris/Leaderboard";

export default function LeaderboardPage() {
  return (
    
      Leaderboard
      
    
  );
}

Replay Viewer Component

Create components/tetris/ReplayViewer.tsx. This file contains two components: ReplayPlayer, which replays a single game from its action log, and ReplayViewer, which handles loading and selection. The key insight in replay playback is that rather than storing 20,000 board snapshots, you store a few hundred action codes and replay them at their original timestamps divided by the speed multiplier. A two-minute game replays in one minute at 2x speed simply by halving each inter-action delay.

ReplayPlayer

ReplayPlayer re-executes the stored action log against a fresh copy of the game engine, advancing state action by action at the original timings. A few design decisions are worth understanding before reading the code.

makeRng implements a seeded pseudo-random number generator (PRNG) using a Mulberry32 algorithm. Math.random() cannot be seeded, so there is no way to reproduce the same piece sequence across two independent runs. By seeding the PRNG with the same value that was used during the original game, the replay generates the exact same piece order the player experienced.

The boardRef, currentRef, and scoreRef pattern mirrors the useRef approach in GameBoard. State updates trigger re-renders, but the applyAction function is called rapidly inside scheduleNext and needs to read the current board and piece synchronously between calls. Refs give it that direct access without waiting for a render cycle.

scheduleNext is a recursive timeout function rather than a setInterval. Each call reads the gap between the current action's timestamp and the next one and schedules itself for exactly that delay divided by the playback speed. This reproduces the original timing precisely, including fast sequences and natural pauses, which a fixed interval cannot do.

"use client";

import React, { useEffect, useRef, useState } from 'react';
import { useQuery } from 'convex/react';
import { api } from '@/convex/_generated/api';
import { Id } from '@/convex/_generated/dataModel';

const WIDTH = 10;
const HEIGHT = 20;
const PIECES: Record = {
  I: [[1, 1, 1, 1]],
  O: [[1, 1], [1, 1]],
  T: [[0, 1, 0], [1, 1, 1]],
  S: [[0, 1, 1], [1, 1, 0]],
  Z: [[1, 1, 0], [0, 1, 1]],
  J: [[1, 0, 0], [1, 1, 1]],
  L: [[0, 0, 1], [1, 1, 1]],
};
const PIECE_COLORS: Record = {
  I: "#00f0f0", O: "#f0f000", T: "#a000f0",
  S: "#00f000", Z: "#f00000", J: "#0000f0", L: "#f0a000",
};
const PIECE_TYPES = Object.keys(PIECES);

// Mulberry32 seeded PRNG. Math.random() cannot be seeded, so it cannot
// reproduce a specific piece sequence. This function returns a callable
// that produces the same sequence every time it is initialized with the
// same seed — matching the sequence the player saw during the original game.
function makeRng(seed: number) {
  let s = seed;
  return function () {
    s |= 0; s = s + 0x6D2B79F5 | 0;
    let t = Math.imul(s ^ s >>> 15, 1 | s);
    t = t + Math.imul(t ^ t >>> 7, 61 | t) ^ t;
    return ((t ^ t >>> 14) >>> 0) / 4294967296;
  };
}

function emptyBoard() {
  return Array.from({ length: HEIGHT }, () => Array.from({ length: WIDTH }, () => 0));
}

function rotate(shape: number[][]) {
  const h = shape.length, w = shape[0].length;
  const out = Array.from({ length: w }, () => Array.from({ length: h }, () => 0));
  for (let r = 0; r < h; r++)
    for (let c = 0; c < w; c++)
      out[c][h - 1 - r] = shape[r][c];
  return out;
}

function canPlace(board: number[][], shape: number[][], x: number, y: number) {
  for (let r = 0; r < shape.length; r++)
    for (let c = 0; c < shape[0].length; c++) {
      if (!shape[r][c]) continue;
      const br = y + r, bc = x + c;
      if (bc < 0 || bc >= WIDTH || br < 0 || br >= HEIGHT || board[br][bc]) return false;
    }
  return true;
}

function ReplayPlayer({ replay }: { replay: any }) {
  const seed = replay.game?.seed ?? 0;

  const [board, setBoard] = useState(emptyBoard());
  const [current, setCurrent] = useState(null);
  const [score, setScore] = useState(0);
  const [level, setLevel] = useState(1);
  const [isPlaying, setIsPlaying] = useState(false);
  const [playbackSpeed, setPlaybackSpeed] = useState(1);

  // Refs hold the mutable game state that applyAction reads and writes
  // between render cycles. Using state here would cause applyAction to
  // close over stale values during rapid action sequences.
  const boardRef = useRef(emptyBoard());
  const currentRef = useRef(null);
  const scoreRef = useRef(0);
  const actionIndexRef = useRef(0);
  const playbackRef = useRef | null>(null);
  const rngRef = useRef(makeRng(seed));

  function spawnPiece(brd: number[][]) {
    const type = PIECE_TYPES[Math.floor(rngRef.current() * PIECE_TYPES.length)];
    const shape = PIECES[type].map((r) => [...r]);
    const x = Math.floor((WIDTH - shape[0].length) / 2);
    if (!canPlace(brd, shape, x, 0)) return;
    const piece = { type, shape, x, y: 0 };
    currentRef.current = piece;
    setCurrent(piece);
  }

  function applyAction(action: { t: number; a: string; p?: any }) {
    const brd = boardRef.current;
    let cur = currentRef.current;

    if (action.a === "START") {
      const newBoard = emptyBoard();
      boardRef.current = newBoard;
      scoreRef.current = 0;
      rngRef.current = makeRng(seed);
      setBoard(newBoard);
      setScore(0);
      setLevel(1);
      spawnPiece(newBoard);
      return;
    }

    if (!cur) return;

    if (action.a === "L" && canPlace(brd, cur.shape, cur.x - 1, cur.y)) {
      cur = { ...cur, x: cur.x - 1 };
    } else if (action.a === "R" && canPlace(brd, cur.shape, cur.x + 1, cur.y)) {
      cur = { ...cur, x: cur.x + 1 };
    } else if (action.a === "D" && canPlace(brd, cur.shape, cur.x, cur.y + 1)) {
      cur = { ...cur, y: cur.y + 1 };
    } else if (action.a === "ROT") {
      const rotated = rotate(cur.shape);
      if (canPlace(brd, rotated, cur.x, cur.y)) cur = { ...cur, shape: rotated };
    } else if (action.a === "HD") {
      // Hard drop: find the lowest valid y position by incrementing until
      // canPlace fails, then lock the piece there immediately. Unlike a
      // soft drop (action "D"), hard drop merges the piece into the board
      // in a single step, clears any completed lines, and spawns the next piece.
      let dropY = cur.y;
      while (canPlace(brd, cur.shape, cur.x, dropY + 1)) dropY++;
      cur = { ...cur, y: dropY };

      const copy = brd.map((r) => [...r]);
      for (let r = 0; r < cur.shape.length; r++)
        for (let c = 0; c < cur.shape[0].length; c++)
          if (cur.shape[r][c]) copy[cur.y + r][cur.x + c] = PIECE_TYPES.indexOf(cur.type) + 1;

      const out: number[][] = [];
      let cleared = 0;
      for (let r = 0; r < HEIGHT; r++) {
        if (copy[r].every((v) => v !== 0)) cleared++;
        else out.push(copy[r]);
      }
      while (out.length < HEIGHT) out.unshift(Array.from({ length: WIDTH }, () => 0));

      if (cleared > 0) {
        scoreRef.current += cleared * 100;
        setScore(scoreRef.current);
        setLevel(Math.floor(scoreRef.current / 1000) + 1);
      }

      boardRef.current = out;
      setBoard([...out]);
      currentRef.current = null;
      setCurrent(null);
      spawnPiece(out);
      return;
    }

    currentRef.current = cur;
    setCurrent({ ...cur });
  }

  function startPlayback() {
    if (!replay?.actions?.length) return;
    actionIndexRef.current = 0;
    boardRef.current = emptyBoard();
    rngRef.current = makeRng(seed);
    setBoard(emptyBoard());
    setCurrent(null);
    setScore(0);
    setLevel(1);
    setIsPlaying(true);

    // scheduleNext is a recursive timeout rather than a setInterval because
    // each action has a different delay: the gap between its timestamp and
    // the next action's timestamp, divided by playback speed. A fixed interval
    // would not reproduce natural timing variations in the original game.
    function scheduleNext() {
      const actions = replay.actions;
      if (actionIndexRef.current >= actions.length) {
        setIsPlaying(false);
        return;
      }
      const curr = actions[actionIndexRef.current];
      const next = actions[actionIndexRef.current + 1];
      const delay = next ? (next.t - curr.t) / playbackSpeed : 500 / playbackSpeed;
      applyAction(curr);
      actionIndexRef.current++;
      playbackRef.current = setTimeout(scheduleNext, Math.max(16, delay));
    }

    scheduleNext();
  }

  function stopPlayback() {
    if (playbackRef.current) clearTimeout(playbackRef.current);
    setIsPlaying(false);
  }

  useEffect(() => () => { if (playbackRef.current) clearTimeout(playbackRef.current); }, []);

  const display = board.map((row, r) =>
    row.map((cell, c) => {
      if (current && r >= current.y && r < current.y + current.shape.length) {
        const sr = r - current.y;
        const sc = c - current.x;
        if (sc >= 0 && sc < current.shape[0].length && current.shape[sr]?.[sc])
          return PIECE_TYPES.indexOf(current.type) + 10;
      }
      return cell;
    })
  );

  const cellPx = 20;
  const displayName = replay.user?.displayName ?? replay.user?.firstName ?? replay.user?.email ?? "Anonymous";

  return (
    
      {displayName}
      
        Score: {replay.game?.score?.toLocaleString() ?? "?"}
        Level: {replay.game?.level ?? "?"}
        Lines: {replay.game?.linesCleared ?? "?"}
        Duration: {Math.round((replay.durationMs ?? 0) / 1000)}s
      

      
        {display.flatMap((row, r) =>
          row.map((cell, c) => {
            const colorIdx = cell >= 10 ? cell - 10 : cell > 0 ? cell - 1 : -1;
            return (
              = 0 ? PIECE_COLORS[PIECE_TYPES[colorIdx]] : "#0f172a",
                  border: "1px solid rgba(100,116,139,0.2)",
                }}
              />
            );
          })
        )}
      

      
        
          Score
          {score.toLocaleString()}
        
        
          Level
          {level}
        
      

      
        
        
      
    
  );
}

ReplayViewer

ReplayViewer handles the outer shell: loading a specific replay by ID when one is provided, fetching the recent replay list when not, and managing which replay is selected for playback. Once a replay is selected, it hands off to ReplayPlayer.

export default function ReplayViewer({ replayId }: { replayId?: Id<"replays"> | string }) {
  const replay = useQuery(
    api.replays.getReplay,
    replayId ? { replayId: replayId as Id<"replays"> } : "skip"
  );
  const recent = useQuery(api.replays.getRecentReplaysWithDetails, {});

  const [selected, setSelected] = useState(null);

  useEffect(() => {
    if (replay) setSelected(replay);
  }, [replay]);

  if (replayId && !replay) {
    return Loading replay...;
  }

  if (!replayId && !recent) {
    return Loading recent replays...;
  }

  if (!selected) {
    if (recent?.length === 0) {
      return No recent replays available.;
    }
    return (
      
        Recent Replays
        
          {recent?.map((r) => {
            const name = r.user?.displayName ?? r.user?.firstName ?? r.user?.email ?? "Anonymous";
            return (
              
                
              
            );
          })}
        
      
    );
  }

  return (
    
      
        
      
      
    
  );
}

Replays Page

Create app/tetris/replays/page.tsx. This mounts ReplayViewer without a replayId, which causes the component to display the recent replays list rather than jumping straight to a specific game.

import React from "react";
import ReplayViewer from "@/components/tetris/ReplayViewer";

export default function ReplaysPage() {
  return (
    
      Replays
      
    
  );
}

Verify All Routes

Start the dev server and confirm each route loads:

pnpm dev

Then check each URL:

http://localhost:3000                            Landing page
http://localhost:3000/tetris/play                Game (no gameId, anonymous start)
http://localhost:3000/tetris/leaderboard         Live leaderboard
http://localhost:3000/tetris/replays             Replay list
http://localhost:3000/tetris/replays?replayId=x  Viewer (shows "not found" until a real ID exists)
http://localhost:3000/mcp-docs                   MCP documentation

If all six routes load without errors, the supporting features are wired up correctly.

Deploying to Vercel

Local development is working. This section gets everything running in production with the correct environment variables, Convex deployment, and ChatGPT connector registration.

Pre-Deployment Checklist

Before deploying, verify these items locally:

# 1. Build succeeds without errors
pnpm build

# 2. All environment variables are present
cat .env.local

# 3. Convex dev is running and schema is synced
pnpm convex dev

# 4. MCP route responds correctly
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

# 5. OAuth discovery endpoint is accessible
curl http://localhost:3000/mcp/.well-known/oauth-protected-resource

Fix any build errors before continuing. Type errors and missing imports will cause the Vercel build to fail even if local dev works.

Deploy Convex to Production

Convex has separate dev and production environments. Your dev deployment runs locally, so you need a separate production deployment for Vercel:

pnpm convex deploy

This command pushes your schema and all functions to a production Convex deployment. After it completes, copy the production URL from the output. Production URLs use your project name rather than a random animal name, so they look like https://your-project-name.convex.cloud rather than the https://happy-animal-123.convex.cloud format you see in development.

Initial Vercel Deployment

vercel --prod

Vercel will ask which project to link to. Select the project you linked in Section 3. After deployment completes, copy your production URL, which looks something like https://tetris-chatgpt-app.vercel.app.

Note that this first deployment runs without your production environment variables. You will redeploy after adding them in the next step, which is why two vercel --prod commands appear in this section.

Configure Production Environment Variables

Your production deployment needs different values for several variables. Go to the Vercel dashboard, open your project, navigate to Settings, then Environment Variables, and add all of the following:

# Convex — use production values from pnpm convex deploy output
CONVEX_DEPLOYMENT=prod:happy-animal-123
NEXT_PUBLIC_CONVEX_URL=https://happy-animal-123.convex.cloud
NEXT_PUBLIC_CONVEX_HTTP_URL=https://happy-animal-123.convex.site

# Kinde — same values as local
KINDE_ISSUER=https://yourcompany.kinde.com
KINDE_CLIENT_ID=your-client-id
KINDE_CLIENT_SECRET=your-client-secret

# Vercel — use your production Vercel URL
VERCEL_PROJECT_PRODUCTION_URL=https://tetris-chatgptapp.com
VERCEL_BRANCH_URL=https://tetris-chatgpt-app.vercel.app
VERCEL_URL=https://tetris-chatgpt-app.vercel.app
VERCEL_ENV=production
NODE_ENV=production

# MCP — use your production Vercel URL
MCP_AUDIENCE=https://tetris-chatgpt-app.vercel.app/mcp
MCP_RESOURCE=https://tetris-chatgpt-app.vercel.app
MCP_DOC_URL=https://tetris-chatgpt-app.vercel.app/mcp-docs

Or set them via CLI:

vercel env add CONVEX_DEPLOYMENT production
vercel env add NEXT_PUBLIC_CONVEX_URL production
vercel env add KINDE_ISSUER production
vercel env add KINDE_CLIENT_ID production
vercel env add KINDE_CLIENT_SECRET production
vercel env add VERCEL_PROJECT_PRODUCTION_URL production
vercel env add VERCEL_BRANCH_URL production
vercel env add VERCEL_URL production
vercel env add VERCEL_ENV production
vercel env add NODE_ENV production
vercel env add MCP_AUDIENCE production
vercel env add MCP_RESOURCE production
vercel env add MCP_DOC_URL production

Update Kinde Callback URLs

Go to Kinde, open your application, navigate to Settings, then Allowed callback URLs, and add your production URLs:

https://tetris-chatgpt-app.vercel.app/api/auth/callback
https://chatgpt.com/connector_platform_oauth_redirect

And in Allowed logout redirect URLs:

https://tetris-chatgpt-app.vercel.app
https://chatgpt.com

The chatgpt.com callback URL is what ChatGPT uses after OAuth completes. Without it, Kinde will reject the redirect and authentication will fail silently.

Redeploy with Production Variables

After setting environment variables, trigger a new deployment so the values take effect:

vercel --prod

Or push a commit to your main branch if you have connected GitHub.

Verify Production Endpoints

Once deployed, test every critical endpoint:

PROD_URL="https://tetris-chatgpt-app.vercel.app"

# MCP tools list
curl -X POST $PROD_URL/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

# OAuth discovery
curl $PROD_URL/mcp/.well-known/oauth-protected-resource

# Landing page loads
curl -I $PROD_URL

All three should return 200 status codes with the expected content.

Registering with ChatGPT

This is the step where your app becomes playable inside ChatGPT. You will enable Developer Mode, create the connector, and walk through the OAuth flow for the first time.

Enable Developer Mode

Go to Settings, then Connectors, then Advanced, and enable Developer Mode.

Important: Enabling Developer Mode automatically disables Memory. If you rely on ChatGPT's Memory feature, note this tradeoff before proceeding. Developer Mode is required for custom MCP connectors and is available on Plus, Pro, and Team plans.

Create the Connector

Go to Settings, then Connectors, then Create, and fill in the form:

Name:           Tetris
Description:    Play Tetris inside ChatGPT with real-time leaderboards
MCP Server URL: https://tetris-chatgpt-app.vercel.app/mcp
Authentication: OAuth

Check "I trust this application" and click Create.

How the OAuth Flow Works

Because your MCP server exposes the /.well-known/oauth-protected-resource endpoint and your tools declare securitySchemes, ChatGPT handles the OAuth flow automatically when a user invokes an authenticated tool for the first time.

The user gets redirected to your Kinde login page, authenticates, approves the requested scopes, and ChatGPT exchanges the authorization code for a token. From that point on, ChatGPT attaches Authorization: Bearer to every MCP request, which is what your extractTokenFromArgs function reads.

Anonymous tools like get_leaderboard and view_replay work immediately without sign-in. Authenticated tools like start_game and finish_game trigger the sign-in flow on first use if the user is not already linked.

Test It

You: "Start a Tetris game"
ChatGPT: [OAuth prompt appears if not signed in, sign in, game widget renders]

You: "Show me the leaderboard"
ChatGPT: [calls get_leaderboard, renders leaderboard widget immediately, no sign-in needed]

If ChatGPT shows an error instead of a widget, check the Vercel function logs: Dashboard, your project, Functions, then click any invocation to see the full request and response.

The two most common issues are the chatgpt.com/connector_platform_oauth_redirect callback URL not being in your Kinde allowlist, and a missing code_challenge_methods_supported: ["S256"] field in your Kinde metadata. The S256 value refers to the PKCE (Proof Key for Code Exchange) challenge method, which ChatGPT requires for its OAuth flow. Kinde includes this by default, but if you are using a custom OAuth provider, verify it is present in your /.well-known/openid-configuration response.

Finishing Up

Custom Domain (Optional)

If you have a domain, add it in Vercel:

vercel domains add yourdomain.com

Then update all environment variables and Kinde callback URLs to use the custom domain. The MCP connector registration in ChatGPT will also need updating to the new URL.

Environment Variable Reference

The complete variable list with descriptions, to help diagnose configuration issues:

# Convex
CONVEX_DEPLOYMENT          # Deployment name (dev:... or prod:...)
NEXT_PUBLIC_CONVEX_URL     # Full Convex URL (must start with https://)

# Kinde — all from your Kinde application settings page
KINDE_ISSUER               # Your Kinde domain (no trailing slash)
KINDE_CLIENT_ID            # Application client ID
KINDE_CLIENT_SECRET        # Application client secret

# MCP — all must use your production URL in production
MCP_AUDIENCE               # Full URL to /mcp route
MCP_RESOURCE               # Root URL of your deployment
MCP_DOC_URL                # URL to /mcp-docs page

The most common misconfiguration is using localhost values in production. MCP_AUDIENCE must match the resource field in your OAuth discovery endpoint. If these do not match, ChatGPT cannot complete the OAuth flow.

Production vs. Preview Deployments

Vercel creates a unique URL for every pull request (for example, tetris-chatgpt-app-git-feature-branch.vercel.app). These preview deployments use the same environment variables, but MCP_AUDIENCE is hardcoded to your production URL, so OAuth will not work in preview by default.

For preview deployments that need working auth, use the VERCEL_BRANCH_URL variable, which the baseURL helper in lib/baseURL.ts already handles:

// lib/baseURL.ts — resolves the correct base URL for each deployment type
export const baseURL =
  process.env.NODE_ENV === "development"
    ? "http://localhost:3000"
    : "https://" +
      (process.env.VERCEL_ENV === "production"
        ? process.env.VERCEL_PROJECT_PRODUCTION_URL
        : process.env.VERCEL_BRANCH_URL || process.env.VERCEL_URL);

The base URL resolves correctly for each deployment automatically. The remaining issue is that Kinde's allowed callback URLs do not include preview URLs. Add https://*.vercel.app/api/auth/callback as a wildcard in Kinde's settings if you want preview auth to work.

Monitoring and Logs

Vercel provides function-level logs accessible in the dashboard.

Build logs cover compilation errors, missing modules, and type errors. Check these first if a deployment fails.

Function logs cover runtime errors, timeouts, and unhandled exceptions. Each invocation is listed individually so you can inspect the exact request and response that caused an error.

Edge Network logs cover CORS issues and header problems. Check these if requests are being blocked before they reach your functions.

For Convex issues, the Convex dashboard at dashboard.convex.dev shows real-time function logs. Every mutation and query is logged with its arguments, return values, and execution time.

Troubleshooting

Even with everything configured correctly, you will hit issues. Here are the most common ones and how to fix them.

ChatGPT shows "action not found" or doesn't recognize your tools

Developer Mode is not enabled. Go to Settings → Connectors → Advanced and enable Developer Mode. This is required for custom MCP connectors and is only available on Plus, Pro, and Team plans.

If Developer Mode is already on, go to Settings → Connectors, find your connector in the list, and click the Refresh icon next to it. ChatGPT caches your MCP manifest and does not automatically discover new tools. A manual refresh is required whenever your tool list changes.

This is almost always a CORS issue. Verify your next.config.ts has the permissive headers configured. The three required headers belong inside the headers() function in your Next.js config:

// next.config.ts
const nextConfig = {
  async headers() {
    return [
      {
        source: "/(.*)",
        headers: [
          { key: "Access-Control-Allow-Origin", value: "*" },
          { key: "Access-Control-Allow-Methods", value: "GET,POST,PUT,DELETE,OPTIONS" },
          { key: "Access-Control-Allow-Headers", value: "*" },
        ],
      },
    ];
  },
};

Also check that MCP_RESOURCE in your Vercel environment variables matches the exact URL ChatGPT is using to reach your app, including https:// and no trailing slash. A mismatch causes the OAuth discovery endpoint to return a resource URL that does not match the incoming request, which silently breaks widget rendering.

OAuth flow never completes (stuck on redirect)

The most common cause is a missing callback URL in Kinde. Go to your Kinde application settings and confirm both of these are in your Allowed Callback URLs:

https://your-app.vercel.app/api/auth/callback
https://chatgpt.com/connector_platform_oauth_redirect

The second URL is what ChatGPT uses to receive the authorization code after the user signs in. Without it, Kinde rejects the redirect and the user sees an error page instead of returning to ChatGPT.

If the callback URLs are correct and the flow still fails, check your MCP_AUDIENCE environment variable. It must exactly match the resource field in your /.well-known/oauth-protected-resource response. ChatGPT echoes this value as the resource parameter throughout the OAuth flow, and Kinde embeds it in the token's aud (audience) claim. When your tool handler calls validateKindeToken, it checks that aud matches MCP_AUDIENCE. If they differ by even a trailing slash, validation fails silently and every authenticated tool call returns an auth error.

Score is not saving (`finish_game` errors)

This usually means finish_game was called before start_game returned a gameId. To confirm, add a log line to the start() function in GameBoard.tsx after the callTool response arrives:

const gameIdToUse = (toolRes as any)?.structuredContent?.gameId;
console.log("Game ID captured:", gameIdToUse); // Add this line
if (gameIdToUse) setGameId(gameIdToUse);

If the log line is missing from the console, start_game either failed or the structuredContent.gameId field was not returned. Check your Vercel function logs for the start_game invocation and confirm your MCP route handler is returning both fields:

return {
  content: [{ type: "text", text: widget }],
  structuredContent: { gameId: String(gameId) },
};

Both fields are required. If structuredContent is absent, callTool returns no game ID and finish_game has nothing to save.

Replay plays wrong pieces (board diverges immediately)

The seeded RNG in ReplayViewer must start from the same position as the original game. Confirm that the START action is the first entry in actionsRef.current. If it is missing, ReplayPlayer never calls spawnPiece with a freshly seeded RNG and the first piece spawns at a different position in the random sequence than the player originally saw. The fix is to ensure actionsRef.current.push({ t: Date.now(), a: "START" }) runs at the very beginning of the start() function, before any other actions are recorded.

Convex mutations throw "argument validation failed"

Your function arguments do not match the schema defined in convex/schema.ts. Open dashboard.convex.dev, go to Logs, and find the failed mutation. The error message will name the exact field that failed.

The two most common mismatches are passing a plain string where a v.id("games") typed ID is expected, and sending undefined for a required field. Both are fixed by checking the mutation's args definition in the relevant convex/ file and ensuring the values you pass match the declared types exactly.

MCP route returns 500 on every request

A 500 on every request almost always means a missing environment variable. A missing NEXT_PUBLIC_CONVEX_URL causes getConvexClient() to throw on every invocation before any tool logic runs.

Go to your Vercel project → Settings → Environment Variables and verify every variable from the deployment checklist is present and scoped to the Production environment. Variables added only to Preview or Development do not apply to production deployments and will not appear in your function's process.env.

Final Data Flow

Here is how a complete game session flows through the system, from user input to ChatGPT rendering:

Every step that touches Convex is transactional. If finishGame fails partway through, none of the writes commit and the game stays in active status, no replay is created, and the leaderboard is not updated. This prevents orphaned records and inconsistent state.

Conclusion

You've built a production Tetris game that runs inside ChatGPT with real-time leaderboards, replay recording, and Kinde OAuth authentication, all delivered through the MCP protocol without the user ever leaving the chat.

The architecture is the important part. The game is just the demonstration. What you actually built is a pattern: an MCP server that authenticates users, stores data in a real-time database, and renders interactive widgets inside ChatGPT.

Swap the game for a task manager, a data dashboard, a booking system, or anything that benefits from a conversational interface and the Convex backend, the Kinde auth flow, and the MCP tool registration all carry over unchanged.

ChatGPT becomes the interface. Your app becomes the capability behind it.

Next Steps

Some ideas for where to take this further:

Mobile gestures: add touch event handlers to GameBoard.tsx so the game is playable on ChatGPT's iOS and Android apps, where keyboard input doesn't work. Tap to rotate, swipe left or right to move, swipe down to soft drop.
AI opponent: implement the Pierre Dellacherie algorithm as a demo mode which is useful for the leaderboard page when no one is actively playing, or as an optional AI assist toggle during a real game.
RBAC: add admin vs. player roles using Kinde's built-in permission system to let admins moderate the leaderboard, delete replays, or ban users.
Submit to the ChatGPT app directory: once you have tested with real users, submit your connector so people can discover it without manually entering your MCP URL. See the submission guidelines.
Multiplayer: Convex's real-time subscriptions make it well-suited for competitive modes. Two players subscribe to the same game document and see each other's board update live with no WebSocket boilerplate required.

Resources

Source code

Complete source code for this tutorial: GitHub repository. If it helped you, consider giving it a star

Core documentation

MCP Protocol Specification: the full MCP authorization spec ChatGPT implements
Vercel ChatGPT Apps SDK: official OpenAI documentation for building apps inside ChatGPT
ChatGPT connector registration: how to connect, test, and publish your app
Apps SDK authentication guide: OAuth 2.1 flow, security schemes, and token verification

Services used

Convex documentation:real-time database, schema, mutations, queries
Kinde documentation: OAuth, JWT validation, user management
Vercel documentation: deployment, environment variables, function logs

Debugging tools

MCP Inspector: walk through OAuth steps and inspect live MCP requests locally before deploying
Convex dashboard: real-time function logs, data browser, and schema viewer
OpenAI egress IPs: allowlist these if you want to restrict MCP access to ChatGPT only

Further reading

Pierre Dellacherie algorithm: the Tetris AI heuristic referenced in Next Steps
MCP authorization spec: PKCE, dynamic client registration, resource metadata

If this tutorial was useful, feel free to share it with others who might benefit. I’d really appreciate your thoughts, you can mention me on X at @wani_shola or connect with me on LinkedIn.

How to Build a To-Do List MCP Server Using TypeScript – with Auth, Database, and Billing

Shola Jegede — Wed, 22 Oct 2025 19:59:14 +0000

In this tutorial, you’ll build a To-Do list MCP server using TypeScript. You’ll learn how to implement authentication, persistence, and billing, to make the server robust and functional for real users.

By the end, you’ll have a working MCP server that:

Authenticates users with Kinde.
Stores to-do data in a Neon Postgres database.
Enforces billing limits and supports upgrades.
Exposes all these features as MCP tools inside Cursor.

This article will walk you through each step, helping you understand design decisions that you can adapt for your own projects.

What You’ll Learn

Why Go Beyond Basic MCP Servers
What You’ll Build
Prerequisites
Project Setup
Database Setup with Neon PostgreSQL
Authentication with Kinde
MCP Server Implementation (with Billing System Integration)
Testing the Complete System
Troubleshooting
Final MCP Server Architecture
Conclusion
- Next Steps
- Resources

Why Go Beyond Basic MCP Servers?

If you read this freeCodeCamp MCP handbook, you learned how to set up a simple MCP server in TypeScript. That’s useful for learning the protocol, but it doesn’t reflect what you need in production.

A real application requires:

Authentication so each user has their own data and permissions.
Persistence so data is stored in a reliable database.
Billing so you can enforce limits and monetize usage.

Without these, an MCP server is just a demo.

What You’ll Build

In this tutorial, you’ll build a to-do MCP server with TypeScript that includes the essentials of a production-ready backend:

Authentication with Kinde
Database persistence with Neon Postgres
Billing enforcement with a free tier and upgrade path
MCP tool exposure so all of this works seamlessly

By the end, you’ll have an MCP server that feels more like the backend of a SaaS app and a template you can extend for your own ideas.

Prerequisites

Before we start, you'll need:

Accounts & Services (all free to use):

Kinde Account → for authentication and billing
Neon Account → for PostgreSQL database
Node.js (v18+) (download)
Cursor IDE → for MCP integration and tool testing (download)

Development Tools:

Terminal/Command line access
Git (optional, for version control)

Project Setup

First, create a new folder:

mkdir todo-mcp-server
cd todo-mcp-server

Then initialize a Node.js project:

npm init -y

Next, install the dependencies your server will need:

npm install @modelcontextprotocol/sdk @neondatabase/serverless @kinde-oss/kinde-typescript-sdk express jsonwebtoken jwks-client express-session

The @modelcontextprotocol/sdk package gives us everything we need to build and expose MCP servers and tools. We’re using @neondatabase/serverless to connect to a Neon Postgres database, and @kinde-oss/kinde-typescript-sdk handles authentication and billing through Kinde.

We’ll also install express, which makes it easy to define routes and handle middleware. To verify user tokens from Kinde, we’ll use jsonwebtoken together with jwks-client. And finally, express-session will take care of managing session state so users can stay logged in across requests.

Next, set up TypeScript and a few type definitions for development:

npm install -D typescript @types/node @types/express @types/express-session tsx

The typescript package enables TypeScript in your project so you can write strongly typed code. The @types/* packages provide type definitions for Node.js, Express, and the session middleware, giving you better autocomplete and error checking in your editor.

Finally, tsx makes it super easy to run TypeScript files directly without the need to pre-compile them before running your app.

Then create a .env file in your project root and paste these variables:

# Database
DATABASE_URL=postgresql://user:pass@host:port/db

# Kinde Authentication
KINDE_ISSUER_URL=https://your-domain.kinde.com
KINDE_CLIENT_ID=your_client_id
KINDE_CLIENT_SECRET=your_client_secret

# Security
JWT_SECRET=your_secret_key

# Environment
NODE_ENV=development

This stores all the credentials that you’ll be using for this project.

Next, create a tsconfig.json in the project root to tell the TypeScript compiler how to handle your code:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "node",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "outDir": "./dist",
    "rootDir": "./src"
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

Finally, update your package.json scripts

{
  "scripts": {
    "build": "tsc",
    "dev": "tsx src/server.ts",
    "start": "node dist/server.js",
    "auth-server": "tsx src/kinde-auth-server.ts",
    "setup-db": "tsx src/setup-db.ts"
  }
}

Database Setup with Neon PostgreSQL

To power your to-do MCP server, you’ll use Neon, a serverless PostgreSQL platform. This gives us a fully managed, scalable database without worrying about infrastructure.

1. Connect your Neon Database

Sign up or log in to your Neon account console.
Create a new project.
Copy the connection string, you’ll need it in your .env file.

2. Create your DB File

Inside your project, create a new file in your src/ folder and name it setup-db.ts. This file will create the tables, indexes, and schema your app relies on.

Database Architecture Overview:

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   setup-db.ts   │───▶│  Neon Database  │───▶│   PostgreSQL    │
│   (Schema)      │    │   (Serverless)  │    │   (Tables)      │
└─────────────────┘    └─────────────────┘    └─────────────────┘

3. Step-by-Step Breakdown of `setup-db.ts`

Step 1: Imports and Database Connection

Start by importing the packages you’ll need and setting up your database connection:

import { neon } from '@neondatabase/serverless';
import dotenv from 'dotenv';

dotenv.config();

const sql = neon(process.env.DATABASE_URL!);

The dotenv package loads your environment variables from a .env file so you don’t have to hardcode secrets in your code. The neon function connects your app to your Neon Postgres database, and the sql variable gives you a clean, type-safe way to run queries.

At this point, your app has everything it needs to talk to the database.

Step 2: Main Setup Function

Now let’s create a function to handle the database setup process:

async function setupDatabase() {
  console.log('Setting up database schema...');
  try {
    // Database operations here
  } catch (error) {
    console.error('Error setting up database:', error);
    process.exit(1);
  }
}

This function keeps all your schema creation logic in one place, making it easy to manage. It also catches and logs any errors instead of failing silently, so you’ll immediately know if something goes wrong. The console messages give you real-time feedback as the setup runs which is super helpful when you’re debugging or deploying.

Step 3: To-Dos Table

Next, create a table to store all user to-dos:

await sql`
  CREATE TABLE IF NOT EXISTS todos (
    id SERIAL PRIMARY KEY,
    user_id TEXT NOT NULL,
    title TEXT NOT NULL,
    description TEXT,
    completed BOOLEAN DEFAULT FALSE,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
  )
`;

This table holds every user’s tasks. The user_id column links each to-do to the user who created it, while the completed field tracks whether a task is done or still pending. The automatic created_at and updated_at timestamps make it easy to sort tasks or track their history over time.

Step 4: Users Table

Now, let’s define a table to manage user accounts and billing details:

await sql`
  CREATE TABLE IF NOT EXISTS users (
    id SERIAL PRIMARY KEY,
    user_id TEXT UNIQUE NOT NULL,
    name TEXT,
    email TEXT,
    subscription_status TEXT DEFAULT 'free' CHECK (subscription_status IN ('free', 'active', 'cancelled')),
    plan TEXT DEFAULT 'free',
    free_todos_used INTEGER DEFAULT 0,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
  )
`;

This table stores each user’s basic information along with their subscription details. The user_id value comes directly from Kinde during authentication. The subscription_status and free_todos_used columns help you enforce billing tiers and limit how many free tasks a user can create before needing to upgrade.

Step 5: Performance Indexes

Next, let’s add a few indexes to make common database operations faster:

await sql`
  CREATE INDEX IF NOT EXISTS idx_todos_user_id ON todos(user_id)
`;

await sql`
  CREATE INDEX IF NOT EXISTS idx_todos_created_at ON todos(created_at)
`;

await sql`
  CREATE INDEX IF NOT EXISTS idx_users_user_id ON users(user_id)
`;

These indexes help speed up lookups and sorting. The first one lets the database quickly find to-dos that belong to a specific user. The second makes it faster to sort tasks by their creation date. And the last one allows fast lookups of users based on their Kinde user_id.

Step 6: Success Logging

After everything runs, it’s helpful to log a clear summary of what was created:

console.log('✅ Database schema created successfully!');
console.log('📋 Tables created:');
console.log('  - todos (id, user_id, title, description, completed, created_at, updated_at)');
console.log('  - users (id, user_id, subscription_status, plan, free_todos_used, created_at, updated_at)');
console.log('🔍 Indexes created for optimal performance');

These logs give you immediate feedback once the setup completes. They show exactly which tables and indexes were created, making it easy to confirm that your database schema is ready to go and everything ran as expected.

Step 7: Error Handling

try {
} catch (error) {
  console.error('❌ Error setting up database:', error);
  process.exit(1);
}

This handles any database setup errors gracefully.

Step 8: Update your .env file in your project root with your Neon database connection string:

DATABASE_URL=postgresql://username:password@host/database?sslmode=require

Step 9: Function Execution

At the bottom of setup-db.ts, run the function:

setupDatabase();

This immediately executes the database setup when the script runs.

Now, run this command in your CLI:

npm run setup-db

Expected output:

🚀 Setting up database schema...
✅ Database schema created successfully!
📋 Tables created:
  - todos (id, user_id, title, description, completed, created_at, updated_at)
  - users (id, user_id, subscription_status, plan, free_todos_used, created_at, updated_at)
🔍 Indexes created for optimal performance

4. Full `setup-db.ts` File

You can view the complete implementation of the setup-db.ts file in the GitHub repo and copy it directly into your project.

Authentication with Kinde

To secure your MCP server, you’ll use Kinde, an authentication provider that makes it easy to handle logins, user sessions, and tokens.

You’ll also connect Kinde to your Neon database so new users are automatically created when they log in.

1. Create a Kinde Application

Go to the Kinde Dashboard.
Create a new application.
Note down these values (you’ll use them shortly):
- Domain: https://your-domain.kinde.com
- Client ID: your-client-id
- Client Secret: your-client-secret

2. Configure Kinde Settings

In your Kinde dashboard, save these URLs as your:

Redirect URL → http://localhost:3000/callback
Logout URL → http://localhost:3000

3. Environment Variables

Update the .env file in your project root with the credentials from your Kinde Dashboard:

KINDE_ISSUER_URL=https://your-domain.kinde.com
KINDE_CLIENT_ID=your_client_id
KINDE_CLIENT_SECRET=your_client_secret

4. Create the Kinde Auth Server

You’ll build an Express server (src/kinde-auth-server.ts) to handle authentication. This server will manage OAuth login and logout with Kinde, store user sessions, and automatically create or update users in your Neon database whenever they sign in.

4.1: Dependencies and Setup

Start by importing the packages you’ll need:

import express from 'express';
import session from 'express-session';
import { createKindeServerClient, GrantType, SessionManager } from '@kinde-oss/kinde-typescript-sdk';
import jwt from 'jsonwebtoken';
import dotenv from 'dotenv';
import { neon } from '@neondatabase/serverless';

The express import powers the web server that will handle authentication routes. express-session manages user sessions so you can persist login state between requests. The @kinde-oss/kinde-typescript-sdk package is the official Kinde SDK, which handles OAuth flows and user authentication.

You’ll use jsonwebtoken to decode and verify user tokens, while dotenv loads environment variables from your .env file. Finally, @neondatabase/serverless connects your server to the Neon Postgres database where user data will be stored.

4.2: Connect to Your Database

const sql = neon(process.env.DATABASE_URL!);

This initializes a type-safe SQL client using your DATABASE_URL.

4.3: Extend login Session

declare module 'express-session' {
  interface SessionData {
    accessToken?: string;
    idToken?: string;
    userInfo?: any;
    userName?: string;
    userEmail?: string;
  }
}

This extends express-session types so you can store Kinde tokens and user info directly in the session.

4.4: Configure Sessions

Now, let’s configure session management so users can stay logged in across requests:

app.use(session({
  secret: process.env.JWT_SECRET || 'your_jwt_secret_key',
  resave: true,
  saveUninitialized: true,
  cookie: { 
    secure: false,
    maxAge: 7 * 24 * 60 * 60 * 1000, // 7 days
    httpOnly: true,
    sameSite: 'lax'
  }
}));

The secret value is used to sign and verify session cookies, ensuring that sessions can’t be tampered with. The cookie settings keep users logged in for up to 7 days and make sure session tokens persist even after a browser refresh.

Setting httpOnly helps protect against cross-site scripting (XSS) attacks, while sameSite: 'lax' allows users to log in across different origins without breaking authentication.

4.5: Create a Session Manager Factory

Next, you’ll define a small helper function to manage session data for each request:

const createSessionManager = (req: any): SessionManager => ({
  getSessionItem: async (key: string) => req.session?.[key],
  setSessionItem: async (key: string, value: any) => {
    if (!req.session) req.session = {};
    req.session[key] = value;
  },
  removeSessionItem: async (key: string) => {
    if (req.session) delete req.session[key];
  },
  destroySession: async () => {
    req.session = {};
  }
});

This function creates a session manager that’s tied to each request. It provides a consistent way to store, retrieve, and clear session data which is exactly what the Kinde SDK needs to keep track of tokens and user info during authentication.

4.6: Create the Kinde Client

Next, set up the Kinde client that will handle the OAuth login and logout flow:

const kindeClient = createKindeServerClient(GrantType.AUTHORIZATION_CODE, {
  authDomain: process.env.KINDE_ISSUER_URL!,
  clientId: process.env.KINDE_CLIENT_ID!,
  clientSecret: process.env.KINDE_CLIENT_SECRET!,
  redirectURL: '',
  logoutRedirectURL: '',
});

This connects your app to Kinde using the Authorization Code grant type which is the most secure option for server-side applications like this one.

The redirectURL and logoutRedirectURL define where users should be sent after logging in or out.

4.7: Create the Home Page Route (GET /)

Then you’ll define a basic route for your home page that checks whether a user is logged in:

app.get('/', (req, res) => {
  const token = req.session?.accessToken;
  const userInfo = req.session?.userInfo;

  if (token) {
    // Show logged-in state with tokens
  } else {
    // Show login button
  }
});

This route reads the session to determine if a user is authenticated. If a token exists, you can display their account details or dashboard. Otherwise, you’ll show a login button that directs them to Kinde’s sign-in page.

4.8: Create the Login Route (GET /login)

Now, add a route that starts the OAuth login process:

app.get('/login', async (req, res) => {
  try {
    const sessionManager = createSessionManager(req);
    const loginUrl = await kindeClient.login(sessionManager);
    res.redirect(loginUrl.toString());
  } catch (error) {
    console.error('Login error:', error);
    res.status(500).send('Login failed');
  }
});

When users visit this route, your app uses the Kinde client to generate a secure login URL and redirects them to Kinde’s hosted login page. Once they log in, Kinde will send them back to your callback route with the necessary tokens.

4.9: OAuth Callback Route (GET /callback)

This is where Kinde redirects users back after login. First, you’ll get the authorization code from Kinde for token exchange:

const fullUrl = `http://${req.headers.host}${req.url}`;
const url = new URL(fullUrl);
const code = url.searchParams.get('code');

Next, you’ll exchange this code for tokens that will be needed for API calls:

const tokenResponse = await fetch(`${process.env.KINDE_ISSUER_URL}/oauth2/token`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    grant_type: 'authorization_code',
    client_id: process.env.KINDE_CLIENT_ID!,
    client_secret: process.env.KINDE_CLIENT_SECRET!,
    code: code,
    redirect_uri: 'http://localhost:3000/callback',
  }),
});

Then, you’ll store these tokens in the session for future requests so users don't need to login every time:

req.session.accessToken = tokenData.access_token;
req.session.idToken = tokenData.id_token;
req.session.userInfo = tokenData;

The next thing you’ll do is to extract the user’s information from JWT and then store this in your database

const user = JSON.parse(Buffer.from(idToken.split('.')[1], 'base64').toString());
req.session.userName = user.given_name || user.name || 'User';
req.session.userEmail = user.email || 'user@example.com';

Finally, add this code that will automatically create or update the user in the database so your MCP server can track to-dos and billing:

const existingUser = await sql`SELECT * FROM users WHERE user_id = ${userId}`;

if (existingUser.length === 0) {
  await sql`
    INSERT INTO users (user_id, name, email, subscription_status, plan, free_todos_used)
    VALUES (${userId}, ${userName}, ${userEmail}, 'free', 'free', 0)
  `;
} else {
  await sql`
    UPDATE users 
    SET name = ${userName}, email = ${userEmail}
    WHERE user_id = ${userId}
  `;
}

4.10: Create the Logout Route (GET /logout)

app.get('/logout', async (req, res) => {
  try {
    req.session.destroy((err) => {
      if (err) {
        console.log('Session destroy error:', err);
      }
      res.redirect('/');
    });
  } catch (error) {
    console.error('Logout error:', error);
    res.status(500).send('Logout failed');
  }
});

This route simply destroys the user’s session, removing all stored tokens and user information. Once the session is cleared, it redirects the user back to the home page, effectively logging them out of the app.

5. Complete Authentication Flow

1. User visits / → sees login button.
2. Clicks login → goes to Kinde.
3. Logs in → redirected back to /callback.
4. Callback exchanges code for tokens.
5. Tokens stored in session.
6. User is created/updated in database.
7. User can now access the MCP server.

6. Why This Matters

By placing Kinde in front of your MCP server, you get a secure and seamless authentication layer without the extra trouble of handling passwords or tokens manually. Your users can log in safely, and their sessions persist across page refreshes without the need to log in again each time they revisit your app.

Every new user who signs in is automatically added to your Neon database, making it easy to track accounts and usage. This setup also lays the groundwork for more advanced features later on, like enforcing billing limits or managing user-specific to-dos.

7. Key Connections

Session ↔ Database: Sync user data
Kinde ↔ Session: Tokens flow from Kinde to session storage
Session ↔ MCP: Tokens passed into the server for access control
Database ↔ MCP: User billing + to-dos read from Neon

8. Full `kinde-auth-server.ts` File

You can view the complete implementation of the kinde-auth-server.ts file in the GitHub repo and copy it directly into your project.

MCP Server Implementation (with Billing System Integration)

Now it’s time to create the main file for your MCP server. This file acts as the entry point, wiring up your database, authentication, tool handlers, and overall flow into a single server.

1. Create Your File

Inside your project, create a new file:

src/server.ts

This file will contain the full implementation of your MCP server.

2. Project Setup and Imports

At the top of the file, import the dependencies you’ll need:

import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
import { neon } from '@neondatabase/serverless';
import jwt from 'jsonwebtoken';
import fs from 'fs';
import path from 'path';

Each import in your MCP server has a specific purpose. The Server class is the foundation that powers your entire implementation. It listens for requests, manages responses, and keeps track of all registered tools. The StdioServerTransport handles communication between your MCP server and other tools through standard input and output, which is exactly how Cursor connects behind the scenes.

The CallToolRequestSchema and ListToolsRequestSchema act as validators, ensuring every incoming request follows the correct structure before it’s processed. This reduces errors and keeps communication between your tools and the MCP client consistent.

neon connects your server to the Neon PostgreSQL database, providing a clean way to manage persistent data like users and to-dos. The jsonwebtoken library decodes and verifies tokens from Kinde, letting you identify and authenticate users securely.

fs is used to read and write authentication tokens locally, which means users don’t need to log in every time. Finally, path helps manage file paths cleanly across different systems, keeping everything organized and portable.

Together, these imports form the backbone of your server’s logic, handling authentication, database access, and reliable communication with Cursor.

3. Database Connection and Configuration

Next, configure your database connection and token storage:

const sql = neon(process.env.DATABASE_URL!);
const TOKEN_FILE = '.auth-token';

The sql constant creates a live connection to your Neon PostgreSQL database using the DATABASE_URL environment variable. Think of it as the bridge that lets your MCP server talk to your database with every query, insert, and update running through this connection.

It’s what allows your server to persist user data, to-dos, and billing information reliably without having to manage complex configurations manually.

The TOKEN_FILE constant, on the other hand, acts as a lightweight local storage system for authentication tokens. Whenever a user logs in, their token is saved here so they don’t have to reauthenticate every time they restart the server.

It’s a simple but effective way to maintain session continuity, especially during local development or testing.

4. Authentication System

To manage tokens, you’ll add three helper functions:

4.1. Get Stored Token

function getStoredToken(): string | null {
  try {
    if (fs.existsSync(TOKEN_FILE)) {
      return fs.readFileSync(TOKEN_FILE, 'utf8').trim();
    }
  } catch (error) {
    console.error('Error reading token file:', error);
  }
  return null;
}

Retrieves a saved JWT token from the local file system.

4.2. Store Token

function storeToken(token: string): void {
  try {
    fs.writeFileSync(TOKEN_FILE, token);
  } catch (error) {
    console.error('Error storing token:', error);
  }
}

Stores a new JWT token locally so authentication persists across server restarts.

4.3. Decode JWT

function decodeJWT(token: string): any {
  try {
    return jwt.decode(token);
  } catch (error) {
    console.error('Error decoding JWT:', error);
    return null;
  }
}

Decodes JWTs to extract user info such as ID, email, and subscription status.

5. Core Helper Functions

5.1. Check Billing Status

async function getKindeBillingStatus(userId: string, accessToken: string): Promise<{ plan: string; features: any; canCreate: boolean; reason?: string }> {
  try {
    const decoded = jwt.decode(accessToken) as any;
    console.log('🔍 JWT Token data for user:', userId, 'Decoded:', decoded);

    const subscription = await sql`
      SELECT * FROM users 
      WHERE user_id = ${userId}
    `;

    if (subscription.length === 0) {
      await sql`
        INSERT INTO users (user_id, name, email, subscription_status, plan, free_todos_used)
        VALUES (${userId}, ${decoded.given_name || decoded.name || 'User'}, ${decoded.email || 'user@example.com'}, 'free', 'free', 0)
      `;
      console.log('👤 New user created:', decoded.given_name || decoded.name, decoded.email);
    }

    const freeTodosUsed = subscription.length > 0 ? subscription[0].free_todos_used : 0;

    if (freeTodosUsed < 1) {
      return {
        plan: 'free',
        features: { maxTodos: 1, used: freeTodosUsed },
        canCreate: true,
        reason: `Free tier - ${1 - freeTodosUsed} todo remaining`
      };
    }

    return {
      plan: 'free',
      features: { maxTodos: 1, used: freeTodosUsed },
      canCreate: false,
      reason: 'You have used your free todo. Please upgrade your plan at  to create more todos.'
    };
  } catch (error) {
    console.error('Error checking Kinde billing:', error);
    return {
      plan: 'free',
      features: { maxTodos: 1 },
      canCreate: false,
      reason: 'Error checking billing status'
    };
  }
}

This checks a user's billing status and enforces a 1-todo free tier. It also auto-creates a user in the database if it doesn’t exist.

5.2. Check To-Do Permission

async function canCreateTodo(userId: string, accessToken: string): Promise<boolean> {
  const billingStatus = await getKindeBillingStatus(userId, accessToken);
  return billingStatus.canCreate;
}

This is a simple wrapper that returns a boolean for permission checks.

6. Core Server Implementation

Initialize your MCP server:

const server = new Server(
  {
    name: 'todo-mcp-server',
    version: '1.0.0',
  },
  {
    capabilities: {
      tools: {},
    },
  }
);

This declares a new MCP server with the capability to register tools.

7. Register Tools

Every tool that your Cursor IDE can use needs to be listed so it knows what’s available. In this part of the server setup, you’re registering all the tools that your MCP server will expose. Think of it like giving Cursor a menu of what your backend can do.

Here’s how that looks in code:

server.setRequestHandler(ListToolsRequestSchema, async () => {
  return {
    tools: [
      {
        name: 'login',
        description: 'Get authentication URL for Kinde login',
        inputSchema: {
          type: 'object',
          properties: {},
        },
      },
      // ... more tools
    ],
  };
});

Tools you’ll create include:

Authentication → login, save_token, logout
To-Do Management → list_todos, create_todo, update_todo, delete_todo
Billing → refresh_billing_status

8. Tool Handlers

Each tool in your MCP server has its own handler. The handler checks if the user is authenticated, talks to the database to perform the request, and returns a clean, structured response that Cursor can display.

This keeps the server organized, secure, and easy to extend later.

8.1. Login Tool

The login tool is responsible for starting the authentication flow with Kinde. When users call it, the server returns a short message explaining how to sign in and store their token.

Once logged in, it lists a few commands that they user can try.

Here’s the handler:

case 'login': {
  return {
    content: [
      {
        type: 'text',
        text: `🔐 **Authentication Required**

To use this MCP server, you need to authenticate with Kinde:

1. **Open your browser** and go to: 
2. **Click "Login with Kinde"** to authenticate
3. **Copy your ID Token** from the page
4. **Use the save_token tool** to store it

**Note:** Make sure the Kinde auth server is running:
\\`\\`\\`bash
npm run auth-server
\\`\\`\\`

After authentication, you can use commands like:
- \\`list todos\\` - List your todos
- \\`create todo\\` - Create a new todo
- \\`refresh billing status\\` - Check your plan status`,
      },
    ],
  };
}

8.2. Save Token Tool

The save_token tool handles storing the user’s authentication token locally so they don’t need to re-authenticate each time they use the MCP server.

Here’s the handler:

case 'save_token': {
  const { token } = args as { token: string };
  storeToken(token);
  return {
    content: [
      {
        type: 'text',
        text: '✅ Token saved successfully! You can now use commands like "list todos" and "create todo" without providing the token each time.',
      },
    ],
  };
}

When a user runs this command and passes in their token, the server saves it to a local file using the storeToken() function. From then on, every other command (like list todos, create todo, or refresh billing status) can automatically authenticate using that stored token.

This small step makes the development flow smoother and keeps authentication persistent across sessions.

8.3. List To-Dos Tool

The list_todos tool retrieves all to-dos that belong to the currently authenticated user. It first checks for a stored authentication token and decodes it to identify the user. If the token is missing or invalid, it asks the user to log in again.

Here’s the handler:

case 'list_todos': {
  const token = getStoredToken();
  if (!token) {
    return {
      content: [
        {
          type: 'text',
          text: '❌ No authentication token found. Please:\\n1. Type "login" to get the authentication URL\\n2. Complete login at \\n3. Copy your token and use "save_token" to store it\\n4. Then try "list todos" again',
        },
      ],
    ];
  }

  const decoded = decodeJWT(token);
  if (!decoded || !decoded.sub) {
    return {
      content: [
        {
          type: 'text',
          text: '❌ Invalid token. Please login again using the "login" command.',
        },
      ],
    ];
  }

  const todos = await sql`
    SELECT * FROM todos 
    WHERE user_id = ${decoded.sub} 
    ORDER BY created_at DESC
  `;

  if (todos.length === 0) {
    return {
      content: [
        {
          type: 'text',
          text: '📝 No todos found. Create your first todo using "create todo"!',
        },
      ],
    ];
  }

  const todosList = todos.map((todo: any) => 
    `**${todo.id}.** ${todo.title}${todo.description ? ` - ${todo.description}` : ''} ${todo.completed ? '✅' : '⏳'}`
  ).join('\\n');

  return {
    content: [
      {
        type: 'text',
        text: `📝 **Your Todos (${todos.length}):**\\n\\n${todosList}`,
      },
    ],
  };
}

Results from this tool are formatted for easy reading in the MCP client, showing each task’s title, description, and completion status. If there are no to-dos yet, it simply prompts the user to create one.

8.4. Create To-Do Tool

The create_todo tool lets authenticated users add new to-dos to their list. It starts by verifying that a valid token exists, ensuring only logged-in users can create tasks. If the token is present, it checks billing limits otherwise, it instructs the user to log in again.

Here’s the handler:

case 'create_todo': {
  const token = getStoredToken();
  if (!token) {
    return {
      content: [
        {
          type: 'text',
          text: '❌ No authentication token found. Please login first.',
        },
      ],
    ];
  }

  const decoded = decodeJWT(token);
  if (!decoded || !decoded.sub) {
    return {
      content: [
        {
          type: 'text',
          text: '❌ Invalid token. Please login again.',
        },
      ],
    ];
  }

  const { title, description, completed } = args as { 
    title: string; 
    description?: string; 
    completed?: boolean; 
  };

  // Check billing status before creating todo
  const canCreate = await canCreateTodo(decoded.sub, token);
  if (!canCreate) {
    const billingStatus = await getKindeBillingStatus(decoded.sub, token);
    return {
      content: [
        {
          type: 'text',
          text: `🚫 **Cannot create todo**

${billingStatus.reason}

**Upgrade your plan:** >,
        },
      ],
    ];
  }

  const result = await sql`
    INSERT INTO todos (user_id, title, description, completed)
    VALUES (${decoded.sub}, ${title}, ${description || null}, ${completed || false})
    RETURNING *
  `;

  // Update free todos used count
  await sql`
    UPDATE users 
    SET free_todos_used = free_todos_used + 1 
    WHERE user_id = ${decoded.sub}
  `;

  return {
    content: [
      {
        type: 'text',
        text: JSON.stringify({
          success: true,
          todoId: result[0].id,
          message: 'Todo created successfully',
          title: result[0].title,
          description: result[0].description,
          completed: result[0].completed
        }, null, 2),
      },
    ],
  };
}

If the user has hit their limit after calling this tool, it returns a clear message explaining why and provides a link to upgrade their plan.

8.5. Update To-Do Tool

The update_todo tool allows an authenticated user to modify an existing to-do’s title, description, or completion status. It first checks for a valid token and decodes it to identify the user. If authentication fails, the tool instructs the user to log in again.

Here’s the handler:

case 'update_todo': {
  const token = getStoredToken();
  if (!token) {
    return {
      content: [
        {
          type: 'text',
          text: '❌ No authentication token found. Please login first.',
        },
      ],
    ];
  }

  const decoded = decodeJWT(token);
  if (!decoded || !decoded.sub) {
    return {
      content: [
        {
          type: 'text',
          text: '❌ Invalid token. Please login again.',
        },
      ],
    ];
  }

  const { todoId, title, description, completed } = args as { 
    todoId: number; 
    title?: string; 
    description?: string; 
    completed?: boolean; 
  };

  const result = await sql`
    UPDATE todos 
    SET 
      title = COALESCE(${title || null}, title),
      description = COALESCE(${description || null}, description),
      completed = COALESCE(${completed !== undefined ? completed : null}, completed),
      updated_at = CURRENT_TIMESTAMP
    WHERE id = ${todoId} AND user_id = ${decoded.sub}
    RETURNING *
  `;

  if (result.length === 0) {
    return {
      content: [
        {
          type: 'text',
          text: '❌ Todo not found or you do not have permission to update it.',
        },
      ],
    ];
  }

  return {
    content: [
      {
        type: 'text',
        text: JSON.stringify({
          success: true,
          message: 'Todo updated successfully',
          todo: result[0]
        }, null, 2),
      },
    ],
  };
}

Once the token is verified, the server updates the specified to-do in the database, using COALESCE to leave any fields unchanged if no new value is provided. The updated_at timestamp is refreshed automatically.

If the to-do doesn’t exist or the user doesn’t have permission to modify it, the tool returns an error message. Otherwise, it responds with the updated to-do in a clean JSON format:

8.6. Delete To-Do Tool

The delete_todo tool allows an authenticated user to remove a specific to-do. It first checks for a valid token and decodes it to identify the user. If the token is missing or invalid, the tool instructs the user to log in again.

Here’s the handler:

case 'delete_todo': {
  const token = getStoredToken();
  if (!token) {
    return {
      content: [
        {
          type: 'text',
          text: '❌ No authentication token found. Please login first.',
        },
      ],
    ];
  }

  const decoded = decodeJWT(token);
  if (!decoded || !decoded.sub) {
    return {
      content: [
        {
          type: 'text',
          text: '❌ Invalid token. Please login again.',
        },
      ],
    ];
  }

  const { todoId } = args as { todoId: number };

  const result = await sql`
    DELETE FROM todos 
    WHERE id = ${todoId} AND user_id = ${decoded.sub}
    RETURNING *
  `;

  if (result.length === 0) {
    return {
      content: [
        {
          type: 'text',
          text: '❌ Todo not found or you do not have permission to delete it.',
        },
      ],
    ];
  }

  return {
    content: [
      {
        type: 'text',
        text: JSON.stringify({
          success: true,
          message: 'Todo deleted successfully',
          deletedTodo: result[0]
        }, null, 2),
      },
    ],
  };
}

This ensures users can only delete their own tasks, keeps the response structured for easy consumption in Cursor, and provides immediate confirmation of the deletion.

8.7. Refresh Billing Status Tool

The refresh_billing_status tool allows an authenticated user to force a fresh check of their billing status from Kinde. It first verifies that a valid token exists and decodes it to identify the user. If the token is missing or invalid, the tool instructs the user to log in again.

Here’s the handler:

case 'refresh_billing_status': {
  const token = getStoredToken();
  if (!token) {
    return {
      content: [
        {
          type: 'text',
          text: '❌ No authentication token found. Please login first.',
        },
      ],
    ];
  }

  const decoded = decodeJWT(token);
  if (!decoded || !decoded.sub) {
    return {
      content: [
        {
          type: 'text',
          text: '❌ Invalid token. Please login again.',
        },
      ],
    ];
  }

  console.log('🔄 Force refreshing billing status for user:', decoded.sub);
  const billingStatus = await getKindeBillingStatus(decoded.sub, token);

  return {
    content: [
      {
        type: 'text',
        text: JSON.stringify({
          success: true,
          message: 'Billing status refreshed successfully!',
          kindeBilling: {
            plan: billingStatus.plan,
            features: billingStatus.features,
            canCreate: billingStatus.canCreate,
            reason: billingStatus.reason,
            upgradeUrl: '',
            selfServicePortal: '',
            lastChecked: new Date().toISOString()
          }
        }, null, 2),
      },
    ],
  };
}

This tool ensures that users always have an up-to-date view of their subscription status and usage limits, providing all necessary information to decide whether they need to upgrade their plan.

8.8. Logout Tool

The logout tool lets a user end their session by clearing the locally stored authentication token. When called, it checks if the token file exists and deletes it. If successful, the tool confirms that the user has been logged out.

Here’s the handler:

case 'logout': {
  try {
    if (fs.existsSync(TOKEN_FILE)) {
      fs.unlinkSync(TOKEN_FILE);
    }
    return {
      content: [
        {
          type: 'text',
          text: '✅ Logged out successfully. Authentication token cleared.',
        },
      ],
    ];
  } catch (error) {
    return {
      content: [
        {
          type: 'text',
          text: '⚠️ Logout completed, but there was an issue clearing the token file.',
        },
      ],
    };
  }
}

This ensures that the session ends cleanly, preventing further use of the MCP server until the user logs in again. It also provides immediate feedback so the user knows the logout process succeeded or if there were minor issues.

9. Full `server.ts` File

You can view the complete implementation of the server.ts file in the GitHub repo and copy it directly into your project.

10. Data Flow & Integration

Now that you’ve wired up authentication, database persistence, and billing checks, let’s step back and look at how everything fits together.

Authentication Flow:

User clicks Login with Kinde.
They are redirected to the Kinde Auth URL.
Kinde issues a JWT token after successful login.
The user copies this token and runs “save_token: ” in the Cursor Chat to store it.
The token is stored in the user’s session.
All future requests include the token for validation.

To-do Flow:

User sends a request (for example, to “create todo” to create a new todo).
The server checks the session for a valid token.
The server verifies the user’s billing plan and usage limits.
If valid, the request hits the Neon Postgres database.
Usage counters are updated and a success response is returned.

Complete Data Flow:

User Input 
   → MCP Server 
      → Authentication Check
         → Billing Check
            → Database Operation
               → Response

Diagram:

flowchart LR
    A[User Input] --> B[MCP Server]
    B --> C{Authenticated?}
    C -- No --> D[Reject Request]
    C -- Yes --> E{Billing OK?}
    E -- No --> F[Reject Request]
    E -- Yes --> G[Database Operation]
    G --> H[Update Usage + Return Response]

This overview shows how the different components work together. Each feature you’ve added (authentication, billing, and persistence) acts as a checkpoint in the request flow.

11. Error Handling & Security

Authentication Security:

JWT Validation: Every request validates JWT token
User Isolation: Users can only access their own to-dos
Token Storage: Tokens are stored locally, not in your database

Database Security:

SQL Injection Prevention: Your MCP server uses parameterized queries
User Scoping: All queries are filtered by user_id
Permission Checks: Every operation validates user ownership

Error Handling:

try/catch returns safe error messages

12. Testing & Deployment

Finally, start the MCP server:

async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
  console.error('Todo MCP server running on stdio');
}

main().catch((error) => {
  console.error('Fatal error in main():', error);
  process.exit(1);
});

Test it by running:

npm run dev

In Cursor, you can now try commands like:

login
save_token: <your-jwt-token>
list todos
create todo
refresh billing status
logout

Testing the Complete System

1. Start the Services

# Terminal 1: Start MCP Server
npm run dev

# Terminal 2: Start Kinde Auth Server
npm run auth-server

2. Configure Cursor MCP

In your Cursor project:

Go to Settings → Tools & MCP → New MCP Server
Edit the ~/.cursor/mcp.json and paste this code below

{
  "mcpServers": {
    "todo-mcp-server": {
      "command": "node",
      "args": ["dist/server.js"],
      "cwd": "/path/to/your/todo-mcp-server",
      "env": {
        "DATABASE_URL": "your-neon-connection-string",
        "KINDE_ISSUER_URL": "",
        "KINDE_CLIENT_ID": "your-client-id",
        "KINDE_CLIENT_SECRET": "your-client-secret",
        "JWT_SECRET": "your-jwt-secret-key",
        "NODE_ENV": "development"
      }
    }
  }
}

3. Test the Complete Flow

Open your Cursor chat window and test MCP commands:

login → Get authentication URL
save_token → Save your token gotten from Kinde
list to-dos → List to-dos
create to-do - Create a to-do
refresh billing status - Check billing

Troubleshooting

Even with everything set up correctly, you might run into issues. Here are some common problems and how to fix them.

1. MCP Server Not Detected

If Cursor can’t see your server:

Double-check the syntax of your ~/.cursor/mcp.json file.
Make sure all file paths in mcp.json are absolute paths (not relative).
Restart Cursor after making changes to the config file.

2. Database Connection Issues

If your Neon database won’t connect:

Confirm your DATABASE_URL environment variable is correctly formatted.
Log into the Neon dashboard and make sure your database is active and not paused.
If you’re using SSL, verify that the SSL mode matches Neon’s connection settings.

3. Kinde Authentication Problems

If login isn’t working as expected:

In your Kinde dashboard, make sure the redirect URLs are set correctly (for example, http://localhost:3000).
Double-check that your client ID and client secret are correct.
Ensure your auth server is running locally on port 3000 before attempting login.

4. Token Errors

If you’re getting token-related errors:

Confirm the token you’re saving is in JWT format (three dot-separated parts).
Make sure the token hasn’t expired.
Use the ID token provided by Kinde, not the access token.

Following these steps should resolve most issues you’ll run into when setting up your MCP server with Cursor, Neon, and Kinde.

Final MCP Server Architecture

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   Cursor IDE    │    │   MCP Server     │    │  Kinde Auth     │
│                 │◄──►│                  │◄──►│   Server        │
│ - MCP Tools     │    │ - Todo CRUD      │    │ - OAuth Flow    │
│ - Chat Interface│    │ - Billing Check  │    │ - Token Storage │
└─────────────────┘    └──────────────────┘    └─────────────────┘
                                │
                                ▼
                       ┌─────────────────┐
                       │ Neon PostgreSQL │
                       │                 │
                       │ - Users Table   │
                       │ - Todos Table   │
                       │ - Billing Data  │
                       └─────────────────┘

Conclusion

You’ve just built a fully functional MCP server with:

Authentication → secure logins with Kinde
Data persistence → to-dos stored in Neon
Billing enforcement → usage limits + upgrade path
Tool exposure → MCP tools accessible in Cursor

This foundation is flexible enough to power more advanced apps while keeping the core flow simple and secure.

Next Steps

Here are some ideas to extend what you’ve built:

Role-based access control (RBAC): create admin vs normal user permissions (see my two-part RBAC guide for reference).
Billing tiers: offer free, pro, and enterprise plans with different limits.
Features: add search, tags, or sharing to to-dos.
Deployment: run the service on a cloud platform with HTTPS and a production-grade database.

Resources

You can find the complete source code for this tutorial in this GitHub repository. If it helped you in any way, consider giving it a star (⭐) to show your support!

Also, if you found this tutorial valuable, feel free to share it with others who might benefit from it. I’d really appreciate your thoughts, you can mention me on X @wani_shola or connect with me on LinkedIn.

How to Use the ChatGPT Apps SDK: Build a Pizza App with Apps SDK

Shola Jegede — Wed, 15 Oct 2025 18:32:52 +0000

OpenAI recently introduced ChatGPT Apps, powered by the new Apps SDK and the Model Context Protocol (MCP).

Think of these apps as plugins for ChatGPT:

You can invoke them naturally in a conversation.
They can render custom interactive UIs inside ChatGPT (maps, carousels, videos, and more).
They run on an MCP server that you control, which defines the tools, resources, and widgets the app provides.

In this step-by-step guide, you’ll build a ChatGPT App using the official Pizza App example. This app shows how ChatGPT can render UI widgets like a pizza map or carousel, powered by your local server.

What You’ll Learn

By following this tutorial, you’ll learn how to:

Set up and run a ChatGPT App with the OpenAI Apps SDK.
Understand the core building blocks: tools, resources, and widgets.
Connect your local app server to ChatGPT using Developer Mode.
Render custom UI directly inside a ChatGPT conversation.

What You’ll Learn
Table of Contents
How ChatGPT Apps Work (Big Picture)
Step 1. Clone the Examples Repo
Step 2. Run the Pizza App Server
Step 3. Expose Your Local Server
Step 4. Walk Through the Pizza App Code
Step 5. Enable Developer Mode in ChatGPT
Challenges (Try These Yourself)
Conclusion

How ChatGPT Apps Work (Big Picture)

Here’s the architecture in simple terms:

ChatGPT (frontend)
   |
   v
MCP Server (your backend)
   |
   v
Widgets (HTML/JS markup displayed inside ChatGPT)

ChatGPT sends requests like: “Show me a pizza carousel.”
MCP Server responds with resources (HTML markup) and tool logic.
Widgets are rendered inline in ChatGPT.

Step 1. Clone the Examples Repo

OpenAI provides an official examples repo that includes the Pizza App. Clone it and install the dependencies using these commands:

git clone https://github.com/openai/openai-apps-sdk-examples.git
cd openai-apps-sdk-examples
pnpm install

After installing, build the components and start the dev server:

pnpm run build  
pnpm run dev

Step 2. Run the Pizza App Server

Navigate to the Pizza App server and start it:

cd pizzaz_server_node
pnpm start

If it works, you should see:

Pizzaz MCP server listening on http://localhost:8000
  SSE stream: GET http://localhost:8000/mcp
  Message post endpoint: POST http://localhost:8000/mcp/messages

This means your server is running locally.

Step 3. Expose Your Local Server

To let ChatGPT communicate with your app, your local server needs a public URL. ngrok provides a quick way to expose it during development.

3.1 Get ngrok

3.2 Install ngrok

macOS:

brew install ngrok

Windows:

Download and unzip ngrok.
Optionally, add the folder to your PATH.

3.3 Connect Your Account

ngrok config add-authtoken

3.4 Start a Tunnel

ngrok http 8000

This gives you a public HTTPS URL (like https://xyz.ngrok.app/mcp).

Step 4. Walk Through the Pizza App Code

The full Pizza App server code is long, so let’s break it down into digestible parts.

4.1 Imports and Setup

import { createServer } from "node:http";
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
import { z } from "zod";

Server and SSEServerTransport come from the Apps SDK.
zod validates input to ensure ChatGPT sends the right arguments.

4.2 Defining Pizza Widgets

Widgets are the heart of the app. Each one represents a piece of UI ChatGPT can display.

Here’s the Pizza Map widget:

{
  id: "pizza-map",
  title: "Show Pizza Map",
  templateUri: "ui://widget/pizza-map.html",
  html: `
    
    
    
  `,
  responseText: "Rendered a pizza map!"
}

id → unique name of the widget.
templateUri → how ChatGPT fetches the UI.
html → actual markup and assets.
responseText → message that shows in chat.

The app defines five widgets:

Pizza Map
Pizza Carousel
Pizza Album
Pizza List
Pizza Video

4.3 Mapping Widgets to Tools and Resources

Next, widgets are converted into tools (things ChatGPT can call) and resources (UI markup ChatGPT can render).

const tools = widgets.map((widget) => ({
  name: widget.id,
  description: widget.title,
  inputSchema: toolInputSchema,
  title: widget.title,
  _meta: widgetMeta(widget)
}));

const resources = widgets.map((widget) => ({
  uri: widget.templateUri,
  name: widget.title,
  description: `${widget.title} widget markup`,
  mimeType: "text/html+skybridge",
  _meta: widgetMeta(widget)
}));

This makes each widget callable and displayable.

4.4 Handling Requests

The MCP server responds to ChatGPT’s requests. For example, when ChatGPT calls a widget tool:

server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const widget = widgetsById.get(request.params.name);
  const args = toolInputParser.parse(request.params.arguments ?? {});
  return {
    content: [{ type: "text", text: widget.responseText }],
    structuredContent: { pizzaTopping: args.pizzaTopping },
    _meta: widgetMeta(widget)
  };
});

This:

Finds the widget requested.
Validates the input (pizzaTopping).
Responds with text + metadata so ChatGPT can render the widget.

4.5 Creating the Server

Finally, the server is bound to HTTP endpoints (/mcp and /mcp/messages) so ChatGPT can stream messages to and from it.

const httpServer = createServer(async (req, res) => {
  // handle requests to /mcp and /mcp/messages
});

httpServer.listen(8000, () => {
  console.log("Pizzaz MCP server running on port 8000");
});

Step 5. Enable Developer Mode in ChatGPT

5.1 Enable Developer Mode

Open ChatGPT
Go to Settings → Apps & Connectors → Advanced Settings
Toggle Developer Mode

When Developer Mode is enabled, ChatGPT should look like this:

5.2 Create App

Go back to Settings → Apps & Connectors
Click Create
Next:
- Name: Enter a name for your app (for example, Pizza App)
- Description: Enter any description for your app (or leave empty)
- MCP Server URL: Paste the public HTTPS URL of your MCP endpoint. Make sure it points directly to /mcp, not just the server root
- Authentication: Choose No authentication
- Check I trust this application
- Click Create to finish

Once your app is connected to ChatGPT, it should look like this:

When you click on the Back icon, you should see your app and other apps that you can connect to and use with ChatGPT:

5.3 Use Your App

To use your app,

Open a new chat in ChatGPT
Click on the + icon
Scroll down to more
You would see your app
Choose Pizza App to start using your app

Here are some commands you can try out with your pizza app in ChatGPT:

Show me a pizza map with pepperoni topping
Show me a pizza carousel with mushroom topping
Show me a pizza album with veggie topping
Show me a pizza list with cheese topping
Show me a pizza video with chicken topping

Each command tells ChatGPT which widget to render, and you can swap in any topping you like.

Below are samples:

Pepperoni topping map:

Extra cheese carousel:

Mushroom topping album:

Challenges (Try These Yourself)

Here are three practical ways to extend your Pizza App. Each one ties directly to the code you already have.

Goal: Create a widget that just shows a short message like “Today’s special: Margherita with basil.”

Where to change:

resources.widgets → duplicate an entry and give it a new id/title.
tools → register it as a new tool.
CallTool handler → detect when it’s called (if (request.params.name === "pizza-special")) and return your special.

Hint:
This widget doesn’t need extra CSS/JS files. Just keep its html to something like

🍕 Today’s special: Margherita

. The idea is to show that widgets can be as simple as plain HTML.

Challenge B: Support Multiple Toppings

Goal: Let users order a pizza with more than one topping, like ["pepperoni", "mushroom"].

Where to change:

toolInputSchema → switch from z.string() to z.array(z.string()).
CallTool handler → after parsing, args.pizzaTopping will be an array. Join it into a string before inserting into HTML/response.
Widget HTML → update the display so it lists all chosen toppings.

Hint:
Console.log the parsed args first to confirm you’re actually getting an array. Then try something like:

const toppings = args.pizzaTopping.join(", ");
return { responseText: `Pizza ordered with ${toppings}` };

Challenge C: Fetch Real Pizza Data from an External API

Goal: Instead of hard-coding content, fetch real pizza info. For example, you could call Yelp’s API to list pizza places in a location, or use a free placeholder API to simulate data.

Where to change:

Inside the CallTool handler for your widget.
Replace the static HTML with a fetch(...) call that builds dynamic HTML from the response.

Hint:
Start small with a free API like JSONPlaceholder. For example:

const res = await fetch("https://jsonplaceholder.typicode.com/posts?_limit=3");
const data = await res.json();

const html = `
  
    ${data.map((p: any) => `${p.title}
`).join("")}
  
`;

return { responseText: "Fetched pizza places!", content: [{ type: "text/html", text: html }] };

Once that works, swap in a real API such as Yelp or Google Maps Places to render actual pizza places.

Conclusion

You just built your first ChatGPT App using the OpenAI Apps SDK. With a bit of JavaScript and HTML, you created a server that ChatGPT can talk to, and rendered interactive widgets right inside the chat window.

This example focused on the pizza app sample provided by OpenAI, but you could build:

A weather dashboard,
A movie finder,
A financial data viewer,
Or even a mini-game.

The SDK makes it possible to blend conversation + interactive UI in powerful new ways.

Explore the OpenAI Apps SDK documentation to go deeper and start building your own apps.

Shola Jegede - freeCodeCamp.org

How to Build an AI-Powered, Local-First Chrome Extension That Turns Your Browsing History into an Intent Map

Table of Contents

What You'll Build

Prerequisites

How openloops Is Structured

The Shared Types

The Manifest

How to Scaffold the Extension

How to Capture Your Browsing History

A Few Shared Helpers

The Database Layer (So Far)

Capturing New Visits Live

Backfilling 14 Days of History

Checkpoint

How to Turn Noise into Sessions

Filtering Out Noise

Extracting Keywords

Extending the Database For Sessions

Segmenting Events into Sessions

Checkpoint

How to Cluster Sessions into Intent Threads

Detecting Ambient Domains

Extending the Database for Intent Threads

Clustering Sessions into Threads

Scoring and Classifying Threads

Putting it Together

Checkpoint

How to Clean Up Self-Referential Noise

The Two Problems

One Definition, Applied Everywhere

Defending the Enrichment Boundary Too

Checkpoint

How to Label Threads with Claude

Storing Keys Locally

The First Version, and How it Broke

Batching the Requests

Building the Prompt and Merging Results

Checkpoint

How to Ground Labels with context.dev

What the API Returns

Fetching One Brand

Enriching Domains in Batches

How Grounding Feeds Back into Labeling

Checkpoint

How to Design the Dashboard

The Three-Column Layout

The Pipeline State Machine

Driving the Welcome Screen from the Same Machine

Wiring the Handlers

The Resume Button

Checkpoint

How to Build the AI Assistant

Grounding the Conversation

Sending a Message

Model and Effort Controls

Rendering Replies and the Empty State

Checkpoint

What You've Built, and Where to Take It

What the Privacy Model Adds Up To

Where to Take it Next

Wrapping up

Resources

Source Code

Core Documentation

Services used

Build tooling

Debugging tools

Further reading

Mastra vs LangChain: Building an AI Agent Pipeline and Analyzing the Data

Table of Contents

Prerequisites

The Tools We're Using

Why This Pipeline

The Project Structure

Building the Mastra Pipeline

The Search Tool

The Agents

The writeCriticStep: Why Write and Critic Live in the Same Step

Token Capture