Stacks

The universal board for AI agents. One board — tasks, issues, bugs, CRM deals, support tickets, roadmap initiatives — that humans drag around a Kanban UI and AI agents drive through a built-in MCP server (54 tools). Anything a person can do in the UI, an agent can do over MCP — authenticated with scoped tokens or OAuth, rate-limited and idempotent, and attributed as a named teammate in the activity feed.

Open source and self-hostable: bring your own Postgres, run it, and the first person to sign in becomes the admin.

What it is

• One surface, five board kinds. Every board is a Kanban of cards, but its kind shapes them: plain Tasks, Bugs (severity, version, resolution), Support tickets (SLA, contact), CRM deals (amount, pipeline stage, contacts), or Roadmap initiatives (quarter, RICE). Convert a board between kinds and the cards adapt in place.
• Agent-native. The same operations power the UI (Server Actions) and the MCP server at /api/mcp. Agents authenticate with scoped personal tokens (read / write / admin) or OAuth 2.1, are rate-limited and idempotency-safe, and appear as named teammates in every activity feed and comment thread.
• Batteries included. Real-time multi-user sync, labels, assignees, due dates, subtasks, comments + @mentions, attachments, saved views, bulk edit, global full-text + semantic search, dashboards, a dependency roadmap graph, notifications, CSV/Trello import, automations, and signed outbound webhooks.
• Self-hostable. Postgres + Next.js, deployable to any Node host. Realtime, file storage, email, and embeddings are optional and degrade gracefully when unconfigured.

Documentation

Full docs live in docs/ and render in-app at /docs:

| Guide | Covers | | --- | --- | | Getting started | Local setup, env vars, seeding, signing in | | User guide | Boards & kinds, tasks, filters, saved views, bulk edit, search, My Work, inbox, dashboards, import/export | | Automations | The rules engine | | Webhooks | Outbound events + HMAC verification | | Agent platform | MCP tokens, scopes, tool catalog, idempotency/concurrency contracts, OAuth 2.1 | | Agent setup variants | Claude Code, claude.ai, Codex/ChatGPT, Cursor, custom SDK agents, the bundled reference agents | | Deployment | Vercel + Neon production setup |

Quick start — let an agent set it up

The fastest path is to hand the setup to a coding agent (Claude Code, Cursor, Codex, …). Paste this prompt and answer its questions as it goes:

Set up and run "Stacks" — an open-source universal board for AI agents
(https://github.com/jentrix-au/stacks-ai) — on my machine.

Do this, explaining each step and pausing whenever you need a credential or a decision
from me:

1. Clone it and cd in:
   git clone https://github.com/jentrix-au/stacks-ai && cd stacks-ai
2. Ensure Node 20+ is available, then run:  corepack enable && pnpm install
3. Database: walk me through creating a free Postgres project at https://neon.tech,
   then ask me to paste the POOLED and DIRECT connection strings.
4. Sign-in: recommend Resend email magic links (have me create a key at
   https://resend.com/api-keys), or Google OAuth
   (https://console.cloud.google.com/apis/credentials) if I prefer. Ask me for the values.
5. Create .env.local from .env.example and fill in DATABASE_URL, DIRECT_URL, the provider
   credentials, and a fresh AUTH_SECRET (generate with: openssl rand -base64 32). Leave the
   optional services (Pusher, Cloudflare R2, Voyage AI) blank — they no-op cleanly.
6. Run:  pnpm db:deploy   (applies migrations to the empty database), then:  pnpm dev
7. Tell me to open http://localhost:3000 and sign in — the first account automatically
   becomes the instance admin.
8. Connect an AI agent over MCP: have me create an access token at
   http://localhost:3000/account/tokens (pick read/write scopes), then wire up my MCP
   client with it. For Claude Code, run:
     claude mcp add --transport http stacks http://localhost:3000/api/mcp \
       --header "Authorization: Bearer <MY_TOKEN>"
   For other clients, add this to their MCP config:
     { "url": "http://localhost:3000/api/mcp",
       "headers": { "Authorization": "Bearer <MY_TOKEN>" } }

Never paste real secrets anywhere except .env.local or my MCP client config.

It clones the repo, installs dependencies, walks you through getting a free database and a sign-in key, writes your .env.local, runs the migrations, and starts the app. Prefer to do it yourself? Follow the manual steps below.

Manual setup (self-hosting)

The first person to sign in on a fresh database becomes the admin; from there you invite your team.

Prerequisites

• Node 20+ (Next.js 16 / React 19) and pnpm 11 — run corepack enable for the pinned version.
• A Postgres 16+ database (see the table below). Migrations enable the pgvector and pg_trgm extensions automatically — no manual setup.
• One sign-in provider (Resend or Google). Everything else is optional.

1. Create the accounts you need

Only the first two rows are required; the rest are optional and no-op cleanly when their env vars are blank.

| Service | Powers | Required? | Sign up | | --- | --- | --- | --- | | Neon — Postgres | The database | Yes | https://neon.tech | | Resend — email | Magic-link sign-in + invite/notification email | A provider | https://resend.com · API keys | | Google Cloud — OAuth | Google sign-in (alternative to Resend) | A provider | Credentials console | | Pusher Channels | Real-time multi-user board sync | Optional | https://pusher.com | | Cloudflare R2 | File attachments (S3-compatible) | Optional | https://dash.cloudflare.com → R2 | | Voyage AI | Semantic search + duplicate detection | Optional | https://dashboard.voyageai.com | | Vercel | Hosting + cron (any Node host also works) | Optional | https://vercel.com/signup |

AUTH_SECRET (and CRON_SECRET, only if you run cron) are generated locally with openssl — no account needed.

2. Database (Neon)

1. Create a project at https://neon.tech → open Connection Details.
2. Copy the pooled string into DATABASE_URL and the direct (unpooled) one into DIRECT_URL; keep ?sslmode=verify-full&channel_binding=require.

Any Postgres 16+ works — a local server can use the same value for both URLs.

3. Sign-in provider (pick one)

• Resend (simplest): create a key at https://resend.com/api-keys; set AUTH_RESEND_KEY and RESEND_FROM. Resend's onboarding sender can email you a link before you verify a domain.
• Google OAuth: create a client at https://console.cloud.google.com/apis/credentials; add the redirect URI http://localhost:3000/api/auth/callback/google (plus your production origin); set AUTH_GOOGLE_ID / AUTH_GOOGLE_SECRET; publish the consent screen (an unpublished screen surfaces as invalid_client / redirect_uri_mismatch).

4. Configure and run

git clone https://github.com/jentrix-au/stacks-ai && cd stacks-ai
corepack enable && pnpm install
cp .env.example .env.local
# Edit .env.local: DATABASE_URL, DIRECT_URL, a sign-in provider, and
# AUTH_SECRET — generate one with:  openssl rand -base64 32
pnpm db:deploy        # apply all migrations to the empty database
pnpm dev              # → http://localhost:3000

pnpm db:deploy applies every migration in order to a brand-new empty database — including the CREATE EXTENSION IF NOT EXISTS pg_trgm / vector steps — so there is nothing to set up by hand.

5. Become the admin

Sign in with your email (Resend) or Google. Open registration is the default, so your first sign-in creates your account and personal workspace (OWNER) and — being the first user on the fresh database — flags you the instance admin. Invite teammates from Members; each new sign-in gets their own workspace.

Set OPEN_SIGNUP=false to switch to invite-only later: existing users keep signing in, but new accounts need a pending workspace invitation (or a match in SIGNUP_ALLOWLIST — comma/space-separated emails and/or @domain suffixes). The first user on an empty DB can always bootstrap.

Optional services

All of these no-op cleanly when their env vars are absent:

| Service | Enables | Without it | | --- | --- | --- | | Resend (AUTH_RESEND_KEY) | Magic-link sign-in, invite + notification emails | No email sign-in; invites/notifications stay in-app | | Pusher (PUSHER_*, NEXT_PUBLIC_PUSHER_*) | Real-time board sync | Changes appear on the next refresh | | Cloudflare R2 (R2_*) | File attachments | Uploads disabled | | Voyage AI (VOYAGE_API_KEY) | Semantic search + duplicate suggestions | Those features return empty | | Cron (CRON_SECRET + a scheduler) | Due/SLA reminders, daily digest, webhook retries, embedding refresh | Those background jobs don't run |

Demo data (optional)

pnpm db:seed creates a demo workspace and demo@stacks.local; in dev you can then use the dev sign-in button to log in without configuring a provider.

Connect an AI agent (MCP)

Stacks exposes the same operations as the UI through a built-in MCP server, so any MCP-capable agent can read and write your boards — authenticated, scoped, and attributed in the activity feed.

1. Create an access token

Sign in, then open /account/tokens → New token:

• Choose least-privilege scopes — read, write, and/or admin.
• Optionally pin it to one workspace and give it a name + emoji (its actions get badged in the activity feed).
• Copy the tm_… token — it's shown only once.

For OAuth-capable clients (below) you can skip this and authorize interactively instead.

2. Point your MCP client at the endpoint

The endpoint is http://localhost:3000/api/mcp locally (https://<your-domain>/api/mcp in production); pass the token as a Bearer header.

Claude Code

claude mcp add --transport http stacks http://localhost:3000/api/mcp \
  --header "Authorization: Bearer tm_..."

Cursor / any Streamable-HTTP MCP client — add to its MCP config (e.g. mcp.json):

{
  "mcpServers": {
    "stacks": {
      "url": "http://localhost:3000/api/mcp",
      "headers": { "Authorization": "Bearer tm_..." }
    }
  }
}

claude.ai / Claude Desktop — add a custom connector pointing at the /api/mcp URL and sign in through the built-in OAuth consent screen (pick scopes + workspace; no token to copy-paste).

The agent now has every Stacks tool (mcp__stacks__*), plus resources and prompts. Full client-by-client guide and the platform contracts (scopes, idempotency, concurrency, error hints): docs/agents-setup.md and docs/agent-platform.md.

Stack

• Next.js 16 (App Router, React 19, Server Actions) on Vercel
• Prisma 7 + Postgres (Neon in prod, pg adapter)
• Auth.js v5 with database sessions — Google OAuth and Resend magic links
• Pusher Channels for real-time board sync
• Cloudflare R2 (S3-compatible) for file attachments
• Resend for invite + magic-link email
• dnd-kit for drag-and-drop, Tailwind v4 + shadcn/ui (base-ui primitives) for the UI
• MCP via mcp-handler at /api/[transport], authed by Bearer PAT

Scripts

| Command | What it does | | ------------------ | ----------------------------------------------------------- | | pnpm dev | Next dev server on :3000 | | pnpm build | `prisma generate && prisma migrate deploy && next buil