Brian — the company brain for AI agents

Brian gives AI agents company-approved judgment: executable procedures, hard rules, guardrails, durable context, escalation, and an audit trail. One multi-tenant MCP service lets each company expose only its own approved knowledge and permitted actions.

What is in this repository

• A React dashboard for signup, login/recovery, onboarding, skill/context management, source connectors, OAuth consent, and agent-connection revocation.
• A TypeScript/Hono server and Supabase Edge bundle exposing the dashboard API and Streamable HTTP MCP.
• PostgreSQL/pgvector migrations with explicit tenant predicates and RLS backstops.
• Supabase Auth integration for human sessions and MCP OAuth 2.1 authorization.
• The publishable, zero-runtime-dependency @brianthebrain/cli package under packages/cli.

The canonical public MCP resource is:

https://api.brianthebrain.app/mcp

OAuth-capable clients configure that URL without a static bearer. An unauthenticated request discovers Supabase OAuth, opens Brian's browser login/consent screen, and returns a short-lived tenant-bound credential to the client.

Public connection quick start

CLI version 0.1.0 is published publicly on npm, so the npx form works without cloning this repository:

npx @brianthebrain/cli signup
npx @brianthebrain/cli connect
npx @brianthebrain/cli doctor

The CLI writes the canonical URL only. It does not accept --token, store OAuth credentials, or modify unsafe configuration. See docs/cli.md and the dated client compatibility matrix.

Local development

Requirements:

• Node.js 22 or newer;
• PostgreSQL with pgvector, using an isolated development/test database;
• a Supabase project for real browser Auth/OAuth flows;
• an OpenAI key for embedding/generative paths that exercise the LLM.

Install each workspace:

npm install
cd server && npm install
cd ../packages/cli && npm install

Run the frontend and API in separate terminals:

npm start

cd server
npm run api

Apply migrations only to the intended database. Database tests must use TEST_DATABASE_URL whose effective schema is not public:

cd server
node --env-file=.env ./node_modules/tsx/dist/cli.mjs src/db/migrate.ts

Core frontend build variables:

REACT_APP_SUPABASE_URL
REACT_APP_SUPABASE_PUBLISHABLE_KEY
REACT_APP_TURNSTILE_SITE_KEY
REACT_APP_BRIAN_MCP_URL=https://api.brianthebrain.app/mcp
REACT_APP_SITE_URL

Core server variables:

DATABASE_URL or SUPABASE_DB_URL
TEST_DATABASE_URL
SUPABASE_URL
SUPABASE_ANON_KEY
BRIAN_APP_URL
MCP_OAUTH_ENABLED
LEGACY_AGENT_TOKENS_ENABLED
MCP_RATE_LIMIT_ENABLED
MCP_PREAUTH_RATE_LIMIT_REQUESTS
MCP_AUTH_RATE_LIMIT_REQUESTS
MCP_RATE_LIMIT_WINDOW_MS

MCP_DCR_ENABLED and MCP_OAUTH_APPROVALS_ENABLED are non-secret, request-time controls in the owner-only app_config table (migration 016), not Edge environment variables. See docs/mcp-oauth.md for the fail-closed rollout and kill-switch procedure.

Provider connector variables are documented separately in docs/connectors.md.

Verification

CI=true npm test -- --watchAll=false
npm run build

cd server
npm run build
node --env-file=.env ./node_modules/vitest/vitest.mjs run
npm run edge:build

cd ../packages/cli
npm test
npm run check
npm pack --dry-run

The public discovery smoke uses no credential:

cd server
npm run smoke:mcp-oauth

Architecture and security

• MCP authentication ADR
• Signup and company lifecycle
• MCP OAuth protocol and troubleshooting
• Tenant isolation
• Token handling
• OAuth outage runbook
• Compromised connection runbook
• Monitoring and alerts
• Backup and restore drill
• Privacy deletion and retention

Release status

The application, migrations 010-016, CLI, privacy lifecycle, and automated local/isolation checks are implemented in this repository. Production currently has migrations through 015; migration 016 and the refreshed runtime artifacts remain a guarded rollout gate. Public signup and universal MCP OAuth are not safe to call generally available until the current migrations are applied, the runtime uses the non-owner brian_app role, Supabase OAuth/asymmetric signing/custom hook and CAPTCHA are configured, the branded domain is live, reviewed legal and operational controls are wired, a dated restore and security review pass, and launch clients complete real end-to-end compatibility runs. The repository records these gates rather than treating local code as proof of external infrastructure.