The complete, step-by-step guide to deploying your Cerebro brain. Start with the core infrastructure, add your preferred capture sources, then layer on optional features.
Time to first working system: ~30 minutes (core + one capture source).
🤖 Using an AI coding tool? See AI-Guided Setup for tips on deploying Cerebro with Claude Code, Cursor, Copilot, or any AI assistant. It references this guide and adds AI-specific workflow advice.
Complete these prerequisites before beginning any phase. Having everything ready upfront prevents delays mid-setup.
| Prerequisite | What to Do | Verify |
|---|---|---|
| GitHub account | Sign up if you don't have one (free) — used to log into Supabase | You can log in to github.com |
| Supabase account | Sign up at supabase.com using GitHub login | You can access the Supabase dashboard |
| OpenRouter account | Sign up at openrouter.ai and add $5 in credits | You have an API key at openrouter.ai/keys |
| Terminal / command line | Mac: Terminal app. Windows: PowerShell. Linux: any terminal | You can run echo hello and see output |
| Supabase CLI installed | Mac: brew install supabase/tap/supabase. Windows: scoop install supabase. Linux: npm install -g supabase |
supabase --version prints a version number |
| Node.js (for npx) | Download from nodejs.org if not installed — needed for some MCP client bridges | node --version prints v18+ |
| An MCP-compatible AI client | At least one of: Claude Desktop, ChatGPT (paid), Claude Code, Cursor, VS Code w/ Copilot | The app is installed and you can open it |
| A text editor | For the credential tracker — Notepad, Notes app, VS Code, anything | You can paste and save text |
Review the decision tree below, decide which features you want, and make sure you have the prerequisites for each before you start.
| Feature | Prerequisites |
|---|---|
| Discord capture | Discord account (free) + a Discord server you own or have admin access to |
| Teams capture | Microsoft 365 tenant with Teams + Azure subscription (free tier works) + M365 admin access to enable sideloading |
| Alexa capture | Amazon account (same one linked to your Alexa/Echo devices) + Alexa Developer Console account (free, same Amazon login) |
| O365 Calendar reminders | Microsoft Entra ID app registration (created during Teams setup, or create a new one) + O365 mailbox for events + M365 admin to grant consent |
| Google Calendar reminders | Google Cloud account (free tier) + personal or Workspace Gmail for the target calendar |
| Daily/Weekly Digest | At least one capture source (Discord or Teams) already set up and working with thoughts captured |
| Digest email delivery | Resend account (free — 100 emails/day) |
| File Attachments | Supabase Storage bucket (free — 1 GB included) |
| Task Management | No additional accounts needed (free) |
| Read-Only MCP (OAuth) | Microsoft Entra ID tenant + Azure CLI + Cloudflare account with a domain |
Tip: If you're setting up Teams capture AND O365 calendar reminders, you'll reuse the same Entra ID app registration for both — just add the
Calendars.ReadWritepermission when you get to Phase 3.
┌─────────────────────────┐
│ Supabase │
│ ┌───────────────────┐ │
│ │ PostgreSQL │ │
┌──────────────────┐ │ │ + pgvector │ │ ┌──────────────────┐
│ Capture Sources │ │ │ + pg_cron │ │ │ AI Clients │
│ │ │ └───────────────────┘ │ │ │
│ Discord ────────┼────▶│ │◀────┼── Claude Desktop │
│ Teams ──────────┼────▶│ Edge Functions: │◀────┼── ChatGPT │
│ Alexa ──────────┼────▶│ cerebro-mcp │◀────┼── Claude Code │
│ MCP Clients ────┼────▶│ cerebro-discord │ │ Cursor │
│ │ │ cerebro-teams │ └──────────────────┘
└──────────────────┘ │ cerebro-alexa │
│ cerebro-digest │
│ │
│ OpenRouter (AI gateway) │
└─────────────────────────┘
Use this to plan which features you'll set up. Phase 1 and Phase 2 are required. Everything else is optional.
START HERE
│
▼
╔═══════════════════════════════════╗
║ PHASE 1: Core Infrastructure ║ ◀── REQUIRED
║ Supabase + OpenRouter + MCP ║
║ ~20 minutes ║
╚═══════════════╤═══════════════════╝
│
✅ Verify: capture + search
✅ via MCP client works
│
▼
╔═══════════════════════════════════╗
║ PHASE 2: Capture Source(s) ║ ◀── AT LEAST ONE REQUIRED
╠═══════════════════════════════════╣
║ ║
║ Choose one or more: ║
║ ┌───────────┐ ┌───────────┐ ║
║ │ Discord │ │ Teams │ ║
║ │ (free) │ │ (O365) │ ║
║ └─────┬─────┘ └─────┬─────┘ ║
║ │ │ ║
║ ▼ ▼ ║
║ Optional: ║
║ ┌───────────────────────┐ ║
║ │ Alexa Voice Capture │ ║
║ │ (Amazon account) │ ║
║ └───────────────────────┘ ║
╚═══════════════╤═══════════════════╝
│
✅ Verify: capture + search
✅ via chosen source(s)
│
▼
┌───── OPTIONAL FEATURES ─────┐
│ │
▼ │
╔══════════════════════╗ │
║ Calendar Reminders ║ │
║ O365 / Google Cal ║ │
╚══════════╤═══════════╝ │
│ │
✅ Verify: date in │
✅ capture → event │
│ │
▼ │
╔══════════════════════╗ │
║ Daily/Weekly Digest ║ │
║ → Chat channels ║ │
╚══════════╤═══════════╝ │
│ │
✅ Verify: manual │
✅ trigger → delivery │
│ │
▼ │
┌───────────────────┐ │
│ + Email Delivery │ │
│ (Resend — free) │ │
└───────┬───────────┘ │
│ │
▼ │
╔══════════════════════╗ │
║ File Attachments ║ │
║ AI vision + storage ║ │
╚══════════╤═══════════╝ │
│ │
✅ Verify: file scan │
✅ + storage works │
│ │
DONE! ◀─────────────────┘
Copy this into a text editor and fill it in as you complete each phase. You'll reference these values throughout setup.
CEREBRO — MASTER CREDENTIAL TRACKER
Keep this file safe. Fill in as you go.
════════════════════════════════════════
PHASE 1: CORE INFRASTRUCTURE
─────────────────────────────
SUPABASE
Account email: ____________
Database password: ____________
Project ref: ____________
Project URL: ____________
Service role key: ____________
OPENROUTER
API key: ____________
GENERATED
MCP Access Key: ____________
MCP Server URL: ____________
MCP Connection URL: ____________
PHASE 2: CAPTURE SOURCES
─────────────────────────
DISCORD (if using)
Application ID: ____________
Public Key: ____________
Bot Token: ____________
TEAMS (if using)
App (client) ID: ____________
Client secret: ____________
Tenant ID: ____________
Bot handle: ____________
ALEXA (if using)
Skill ID: ____________
Function URL: ____________
PHASE 3: CALENDAR REMINDERS
────────────────────────────
O365 (if using)
GRAPH_TENANT_ID: ____________
GRAPH_CLIENT_ID: ____________
GRAPH_CLIENT_SECRET: ____________
CALENDAR_USER_EMAIL: ____________
GOOGLE (if using)
GOOGLE_CALENDAR_ID: ____________
Service account JSON: (stored separately)
PHASE 4: DIGEST + EMAIL
────────────────────────
RESEND (if using email)
API key: ____________
From address: ____________
To address(es): ____________
════════════════════════════════════════
What you'll build: A Supabase database with vector embeddings, an MCP server that lets any AI assistant capture and search your thoughts, and connections to your AI tools.
Before starting Phase 1, confirm you have:
- Supabase account created and you can access the dashboard
- OpenRouter account created with $5+ credits loaded
- Supabase CLI installed (
supabase --versionworks in your terminal) - An MCP-compatible AI client installed (Claude Desktop, ChatGPT, Claude Code, etc.)
- Your credential tracker file open and ready
Follow the complete guide: Getting Started →
This covers:
- Create a Supabase project (free tier)
- Set up the database (thoughts table, vector search, security)
- Get an OpenRouter API key (AI gateway)
- Generate an access key
- Deploy the MCP server Edge Function
- Connect to your AI client (Claude Desktop, ChatGPT, Claude Code, Cursor)
Do NOT proceed until all of these pass:
| # | Test | Expected Result |
|---|---|---|
| 1 | Visit https://YOUR_REF.supabase.co/functions/v1/cerebro-mcp in browser |
Page loads (not 404/500) |
| 2 | In your AI client: "Remember this: testing Cerebro setup" | Confirmation with extracted metadata |
| 3 | In your AI client: "What did I capture about testing?" | Returns the thought you just captured |
| 4 | Supabase Dashboard → Table Editor → thoughts |
At least 1 row with metadata.source = "mcp" |
✅ All 4 pass? Continue to Phase 2.
What you'll build: One or more chat-based entry points so you can capture thoughts from your phone, desktop, or voice — not just your AI coding tools.
Before starting Phase 2, confirm:
- Phase 1 is complete — all 4 verification gate tests pass
- You've decided which capture source(s) to set up (see prerequisites table in "Before You Start")
- You have the required accounts for your chosen source(s):
- Discord: Discord account + a server you own/admin
- Teams: M365 tenant + Azure subscription + M365 admin access
- Alexa: Amazon account + Alexa Developer Console account
Choose at least one capture source. You can add more later.
What you need: A Discord account (free) and a Discord server you control.
What you get: /capture and /search slash commands that work on desktop, mobile, and web.
Follow the complete guide: Discord Setup →
| # | Test | Expected Result |
|---|---|---|
| 1 | /capture thought:testing Discord integration |
"Thinking..." → confirmation with metadata |
| 2 | /search query:testing |
Returns matching thoughts with similarity scores |
| 3 | Supabase → thoughts table |
New row with metadata.source = "discord" |
| 4 | Visit Edge Function URL in browser | {"status":"ok","service":"cerebro-discord"} |
What you need: Microsoft 365 tenant with Teams, Azure subscription (Bot is free F0 tier), admin access for sideloading.
What you get: DM the bot or @mention it in any Teams channel. Works on desktop, web, iOS, and Android.
Follow the complete guide: Teams Setup →
| # | Test | Expected Result |
|---|---|---|
| 1 | DM the Cerebro bot: "testing Teams integration" | Confirmation reply with extracted metadata |
| 2 | @mention in a channel: "@Cerebro architecture review" | Threaded reply with confirmation |
| 3 | Supabase → thoughts table |
New rows with metadata.source = "teams" |
| 4 | Visit Edge Function URL in browser | {"status":"ok","service":"cerebro-teams"} |
Note: Alexa is best added alongside Discord or Teams, since it can't receive push notifications (digests). It's great for hands-free capture and queries.
What you need: Amazon account (same as your Alexa devices), Alexa Developer Console account (free).
What you get: "Alexa, tell cerebro ..." — capture, search, task management, stats, and digest queries by voice.
Follow the complete guide: Alexa Setup →
| # | Test | Expected Result |
|---|---|---|
| 1 | Simulator: "open cerebro" | "Welcome to Cerebro..." |
| 2 | Simulator: "tell cerebro I need to buy groceries" | "Captured: I need to buy groceries. Tagged as task." |
| 3 | Simulator: "ask cerebro about groceries" | "I found 1 result..." |
| 4 | Supabase → thoughts table |
New row with metadata.source = "alexa" |
✅ At least one capture source verified? Your Cerebro is fully functional. The features below are optional enhancements.
What you'll build: Automatic calendar event creation when you capture a thought that mentions a future date or time. Works across ALL capture sources.
Before starting Phase 3, confirm:
- Phase 1 is complete — core infrastructure verified
- At least one capture source works — Phase 2 verification gate passed
- You have the accounts/access for your chosen calendar(s):
- O365 Calendar: Entra ID app registration (from Teams setup or new), M365 admin access to grant
Calendars.ReadWriteconsent, an O365 mailbox for events - Google Calendar: Google Cloud account, a Gmail/Google Calendar to target
- O365 Calendar: Entra ID app registration (from Teams setup or new), M365 admin access to grant
What you need: Office 365 calendar and/or Google Calendar.
Example: Saying "remind me to check the deployment logs next Friday at 10am" from any capture source → event appears on your calendar.
Follow the complete guide: Reminders Setup →
| # | Test | Expected Result |
|---|---|---|
| 1 | Capture: "remind me to call the dentist next Wednesday at 5 AM" | Confirmation includes "⏰ Reminder created on ..." |
| 2 | Check your calendar app | Event appears for next Wednesday at 5:00 AM |
| 3 | Supabase → thought's metadata |
Contains has_reminder: true, reminder_title, reminder_datetime |
| 4 | Capture: "I like PostgreSQL" (no date) | No calendar event created (correctly ignored) |
What you'll build: Automated daily and weekly summaries delivered to your chat channels (Teams, Discord, or both). Optionally adds email delivery.
Before starting Phase 4, confirm:
- Phase 1 is complete — core infrastructure verified
- At least one capture source works — Phase 2 verification gate passed
- You have captured several thoughts — the digest needs content to summarize (at least 5-10 thoughts recommended)
- (For email) You have a Resend account created (free tier)
What you need: Core setup + at least one capture source with some thoughts captured.
The daily digest runs every morning (6 AM Central) with a concise summary. The weekly digest runs Sundays (noon Central) with deeper pattern analysis.
Follow the complete guide: Digest Setup →
| # | Test | Expected Result |
|---|---|---|
| 1 | Capture several thoughts first (need content to summarize) | Multiple rows in thoughts table |
| 2 | curl -X POST https://YOUR_REF.supabase.co/functions/v1/cerebro-digest -H "Content-Type: application/json" -d '{"period":"daily"}' |
JSON response with "success": true |
| 3 | Check your Discord/Teams channel | Digest message appears |
| 4 | select * from digest_channels; |
Rows for your active channels with enabled = true |
| 5 | select * from cron.job; |
Shows cerebro-daily-digest and cerebro-weekly-digest |
Want the digest in your inbox too? Add Resend (free — 100 emails/day, 3,000/month).
This is covered in the digest guide under Email Setup with Resend.
| # | Test | Expected Result |
|---|---|---|
| 1 | Set RESEND_API_KEY, DIGEST_EMAIL_TO, DIGEST_EMAIL_FROM |
Secrets set successfully |
| 2 | Manually trigger: curl -X POST ... -d '{"period":"daily"}' |
JSON shows email delivery in response |
| 3 | Check your inbox | HTML-styled digest email with gradient header |
Goal: Scan images, PDFs, and documents posted in Teams or Discord.
- Phase 1 complete (core infrastructure)
- At least one capture source working (Teams or Discord)
- Supabase Storage bucket not yet created
- Run schema migration:
schemas/core/004-add-file-columns.sql - Create
cerebro-filesstorage bucket in Supabase Dashboard - Redeploy capture Edge Functions
- (Discord only) Re-register slash commands with file option
📖 Full guide → File Attachments Setup
- Send an image to Teams/Discord → bot replies with AI description
- Send a PDF → content is scanned and captured
- "Remove file" button works → file deleted, scan text preserved
-
list_thoughtswithhas_file: truereturns file thoughts only
Goal: Complete, reopen, and delete tasks with natural language across all capture points.
- Phase 1 complete (core infrastructure)
- At least one capture source working
- Run schema migration:
schemas/core/005-add-status-column.sql - Redeploy all Edge Functions
- (Discord only) Re-register slash commands with new task commands
- (Alexa only) Update interaction model with DeleteTaskIntent
📖 Full guide → Task Management Setup
- Capture a task thought → confirmed as "task" type
- Complete the task with "done: description" → ✅ marked done
- Reopen with "reopen: description" → 🔄 reopened
- Delete with "delete: description" → 🗑️ deleted
-
list_thoughtswithstatus: "done"shows completed tasks
Share read-only access to your brain via a second MCP server protected by Microsoft Entra ID OAuth — no static API keys.
| Prerequisite | Why |
|---|---|
| Core infrastructure (Phase 1) complete | Database and primary MCP server must exist |
| Microsoft Entra ID tenant | OAuth authentication provider |
| Azure CLI installed and logged in | For creating the app registration |
| Cloudflare account with a domain | For the OAuth discovery proxy (custom domain required by MCP spec) |
- Create an Entra ID app registration (single tenant, SPA redirect URIs, public client)
- Expose API with
Thoughts.Readscope, preauthorize VS Code client ID - Deploy
integrations/mcp-server-readonly/Edge Function - Deploy
integrations/cloudflare-worker/Cloudflare Worker (OAuth discovery proxy at custom domain) - Set Supabase secrets (
MCP_READONLY_TENANT_ID,MCP_READONLY_CLIENT_ID) - Connect MCP clients — VS Code handles OAuth flow automatically
📖 Full guide → Read-Only MCP Setup
- Health endpoint returns
{"status":"ok","service":"cerebro-mcp-readonly","auth":"entra-id"} - OAuth discovery at
/.well-known/oauth-protected-resourcereturns JSON pointing to Entra ID - Unauthenticated request returns 401 with
WWW-Authenticateheader - VS Code OAuth flow triggers Entra ID login
- After OAuth login, search returns results
- Only 3 read-only tools available (no capture, complete, reopen, or delete)
Auto-pulls Outlook mail, calendar, OneNote, and OneDrive/SharePoint items into the thoughts table on a daily schedule. An AI gatekeeper decides save/skip per item; only items "worth keeping" become thoughts. Saved items appear in the next morning's digest under 📧 Important Emails / 📅 Calendar / 📝 OneNote / 📄 Documents.
| Prerequisite | Why |
|---|---|
| Phase 1 complete | Database, MCP, OpenRouter |
| Phase 3 complete (Entra app for calendar reminders) | Reuses the same app registration and GRAPH_* secrets |
| Tenant admin | Must grant admin consent for new application permissions |
- Add 4 application (app-only) permissions to the Entra app:
Mail.Read,Calendars.Read,Notes.Read.All,Files.Read.All - Grant admin consent (portal or
https://login.microsoftonline.com/{tenant-id}/v2.0/adminconsent?client_id={client-id}&scope=https://graph.microsoft.com/.default) - Apply migrations 011 + 012
- Deploy
integrations/cerebro-graph-ingest/ - Manual test with
curl -X POST .../functions/v1/cerebro-graph-ingest -H "x-brain-key: $BRAIN_ACCESS_KEY" -d '{"source":"mail"}' - Confirm cron is scheduled at
0 11 * * *UTC
📖 Full guide → Graph Ingest Setup
- App-only token request succeeds (
POST /oauth2/v2.0/tokenreturnsaccess_token) -
GET /v1.0/users/{userId}/messages?$top=1returns a subject line - Migration 011 created
graph_ingest_statewith 4 seeded rows - Migration 012 scheduled
cerebro-graph-ingest-daily(verify withSELECT * FROM cron.job WHERE jobname = 'cerebro-graph-ingest-daily') - Manual
{"source":"all"}returns{"ok": true, "results": {...}} - At least one row exists with
metadata->>'source' LIKE 'graph-%'
Your Cerebro brain is now operational. Here's what you've built:
| Component | Status |
|---|---|
| Core database + vector search | ✅ Required |
| MCP server for AI tools | ✅ Required |
| Capture source(s) | ✅ Required (1+) |
| Calendar reminders | Optional |
| Daily/weekly digest | Optional |
| Email delivery | Optional |
| File attachments | Optional |
| Task management | Optional |
| Read-only MCP with OAuth | Optional |
| Microsoft Graph daily ingest | Optional |
- Capture everything — random thoughts, meeting notes, decisions, ideas. The AI extracts structure automatically.
- Search by meaning — "What did I decide about the database?" finds thoughts about PostgreSQL choices even if you never said "database."
- Mix sources — capture from Discord on your phone, Teams on your desktop, Alexa while walking. It all goes to the same brain.
- Review your digests — the weekly digest surfaces patterns you might miss day-to-day.
| Variable | Set In | Used By | Required |
|---|---|---|---|
MCP_ACCESS_KEY |
Phase 1 | MCP server | Yes |
OPENROUTER_API_KEY |
Phase 1 | All functions | Yes |
DISCORD_PUBLIC_KEY |
Phase 2 | Discord capture | If using Discord |
DISCORD_BOT_TOKEN |
Phase 2 | Discord capture + Digest | If using Discord |
TEAMS_BOT_APP_ID |
Phase 2 | Teams capture + Digest | If using Teams |
TEAMS_BOT_APP_SECRET |
Phase 2 | Teams capture + Digest | If using Teams |
ALEXA_SKILL_ID |
Phase 2 | Alexa capture | Recommended |
GRAPH_TENANT_ID |
Phase 3 | Calendar reminders | If using O365 cal |
GRAPH_CLIENT_ID |
Phase 3 | Calendar reminders | If using O365 cal |
GRAPH_CLIENT_SECRET |
Phase 3 | Calendar reminders | If using O365 cal |
CALENDAR_USER_EMAIL |
Phase 3 | Calendar reminders | If using O365 cal |
GOOGLE_SERVICE_ACCOUNT_JSON |
Phase 3 | Calendar reminders | If using Google cal |
GOOGLE_CALENDAR_ID |
Phase 3 | Calendar reminders | If using Google cal |
RESEND_API_KEY |
Phase 4 | Digest email | If using email |
DIGEST_EMAIL_TO |
Phase 4 | Digest email | If using email |
DIGEST_EMAIL_FROM |
Phase 4 | Digest email | If using email |
MCP_READONLY_TENANT_ID |
Phase 7 | Read-only MCP OAuth | If using read-only MCP |
MCP_READONLY_CLIENT_ID |
Phase 7 | Read-only MCP OAuth | If using read-only MCP |
MCP_READONLY_ALLOWED_USERS |
Phase 7 | Read-only MCP OAuth | Optional user restriction |
GRAPH_USER_ID |
Phase 8 | Microsoft Graph daily ingest | If using graph-ingest (also used by reminders) |
Note:
SUPABASE_URLandSUPABASE_SERVICE_ROLE_KEYare automatically available in all Supabase Edge Functions.Note: File Attachments (Phase 5) requires no new environment variables — it uses existing Supabase credentials and the
OPENROUTER_API_KEYalready configured in Phase 1.Note: Task Management (Phase 6) requires no new environment variables — it uses existing Supabase credentials and the
OPENROUTER_API_KEYalready configured in Phase 1.
| Symptom | Likely Cause | Fix |
|---|---|---|
| 404 on Edge Function URL | Function not deployed | supabase functions deploy <name> --no-verify-jwt |
| 401 from MCP server | Wrong access key | Check MCP_ACCESS_KEY matches x-brain-key header value |
| Tools don't appear in Claude | Connector not added | Settings → Connectors → add the MCP Connection URL |
| Discord commands missing | Propagation delay | Global commands take up to 1 hour; use guild-specific for instant |
| Teams bot no reply | Wrong messaging endpoint | Azure Bot → Configuration → verify URL matches function |
| Alexa "problem with skill" | Function error | supabase functions logs cerebro-alexa --project-ref YOUR_REF |
| Calendar event not created | Missing credentials | supabase secrets list — check GRAPH_* or GOOGLE_* vars |
| Digest not delivered | No registered channels | Capture a thought from Teams/Discord first to auto-register |
| Cron not firing | Extensions disabled | Enable pg_cron and pg_net in Supabase Dashboard |
| Email not received | Resend domain restriction | Default onboarding@resend.dev only sends to account owner |
| Function | Endpoint | Deploy Command |
|---|---|---|
| MCP Server | cerebro-mcp |
supabase functions deploy cerebro-mcp --no-verify-jwt |
| Discord | cerebro-discord |
supabase functions deploy cerebro-discord --no-verify-jwt |
| Teams | cerebro-teams |
supabase functions deploy cerebro-teams --no-verify-jwt |
| Alexa | cerebro-alexa |
supabase functions deploy cerebro-alexa --no-verify-jwt |
| Digest | cerebro-digest |
supabase functions deploy cerebro-digest --no-verify-jwt |
| Graph Ingest | cerebro-graph-ingest |
supabase functions deploy cerebro-graph-ingest --no-verify-jwt |
Redeploy all functions after code changes:
supabase functions deploy cerebro-mcp --no-verify-jwt && \
supabase functions deploy cerebro-discord --no-verify-jwt && \
supabase functions deploy cerebro-teams --no-verify-jwt && \
supabase functions deploy cerebro-alexa --no-verify-jwt && \
supabase functions deploy cerebro-digest --no-verify-jwt && \
supabase functions deploy cerebro-graph-ingest --no-verify-jwt