WritBase
MCP-native task management for AI agent fleets
A control plane for AI agents and human supervisors. Persistent task registry with scoped permissions, inter-agent delegation, and full provenance — all accessible via MCP.
Why WritBase?
AI agents need a shared, persistent task registry — not ephemeral in-memory state that vanishes between sessions. WritBase gives your agent fleet:
- One source of truth — Tasks live in Postgres, not scattered across files and chat threads
- Scoped permissions — Each agent gets exactly the access it needs, nothing more
- Full provenance — Every change is recorded: who, what, when, and why
- Inter-agent delegation — Agents can assign tasks to each other with depth limits and cycle detection
- MCP-native — Agents connect via the Model Context Protocol, no custom integration needed
Getting Started
Option A: CLI Setup (recommended)
No repo clone needed. Just npx:
npx writbase init # Interactive setup — configures Supabase credentials
npx writbase migrate # Apply database schema
npx writbase key create # Create your first agent key
That's it. Your MCP endpoint is live at:
https://<project-ref>.supabase.co/functions/v1/mcp-server/mcp
Prerequisites: Node 18+, Supabase CLI, a Supabase project (free tier works)
Deploy the Edge Function:
npx supabase functions deploy mcp-server --no-verify-jwtSee the CLI README for all commands.
Option B: Manual Setup
git clone https://github.com/Writbase/writbase.git
cd writbase && npm install
# Create a free project at supabase.com/dashboard, then:
npx supabase link --project-ref <your-project-ref>
npx supabase db push
npx supabase functions deploy mcp-server --no-verify-jwt
Optional dashboard:
cp .env.example .env.local→ edit with your Supabase URL + anon key →npm run devSee the Deployment Guide for Vercel hosting and self-hosted Supabase.
2. Create a project and agent key
Via the CLI (npx writbase key create), the dashboard, or a manager agent:
- Create a project — e.g.,
my-app. Optionally add departments (backend,frontend,devops) - Create an agent key — name it, pick the
workerrole, save the key (wb_<key_id>_<secret>— shown once) - Grant permissions —
writbase key permit my-agent --grant --project my-app --can-read --can-create --can-update(or via dashboard)
3. Connect your MCP client
claude mcp add writbase \
--transport http \
--url https://<project-ref>.supabase.co/functions/v1/mcp-server/mcp \
--header "Authorization: Bearer wb_<key_id>_<secret>"
Add to .cursor/mcp.json:
{
"mcpServers": {
"writbase": {
"type": "streamableHttp",
"url": "https://<project-ref>.supabase.co/functions/v1/mcp-server/mcp",
"headers": { "Authorization": "Bearer wb_<key_id>_<secret>" }
}
}
}
Add to .vscode/mcp.json:
{
"servers": {
"writbase": {
"type": "http",
"url": "https://<project-ref>.supabase.co/functions/v1/mcp-server/mcp",
"headers": { "Authorization": "Bearer wb_<key_id>_<secret>" }
}
}
}
See the MCP Config Reference for all supported clients.
4. Use it
Ask your agent:
"Check my WritBase permissions" → calls info
"Create a task in my-app: Fix login bug" → calls add_task
"Mark it as in_progress" → calls update_task (with version for concurrency)
"Show all high priority tasks" → calls get_tasks with priority filter
5. Scale up
Each agent gets its own key with exactly the permissions it needs — nothing more.
Full walkthrough: Getting Started Guide — permissions, departments, troubleshooting
MCP Tools
Worker Tools (all agents)
Manager Tools (manager agents only)
Features
- Multi-tenant workspaces — Signup auto-provisions an isolated workspace
- Dynamic MCP schema — Tool visibility and parameter enums adapt per agent's role and permissions
- 6 permission types —
can_read,can_create,can_update,can_assign,can_comment,can_archive - Project + department scoping — Permissions are granted per (project, department) pair
- Optimistic concurrency — Version-based conflict detection prevents silent overwrites
- Cursor pagination — Efficient traversal of large task sets
- Rate limiting — Per-agent-key request throttling
- Request logging — Every MCP call logged with latency, status, and agent context
Architecture
┌─────────────┐ ┌──────────────────┐ ┌──────────────┐
│ MCP Client │────▶│ Edge Function │────▶│ Postgres │
│ (Agent) │◀────│ (Hono + MCP SDK)│◀────│ (Supabase) │
└─────────────┘ └──────────────────┘ └──────────────┘
│
┌──────┴──────┐
│ Next.js 16 │
│ Dashboard │
└─────────────┘
- Backend: Supabase (Postgres + Edge Functions with Deno runtime)
- Transport: Streamable HTTP (MCP SDK)
- Frontend: Next.js 16 (App Router) + Tailwind CSS
- Auth: Supabase Auth (humans) + SHA-256 agent keys (agents)
Deployment Options
See docs/deployment.md for detailed setup instructions.
Documentation
- Getting Started — Deploy, create an agent key, connect your MCP client, and manage tasks
- CLI Reference —
npx writbase init,migrate,key,status - Deployment Guide — Supabase Cloud, Vercel, and self-hosted setup
- Core Concepts — Permissions, provenance, error codes, delegation
- MCP Config Reference — Client configs for Claude Code, Cursor, VS Code, Windsurf
Contributing
See CONTRIBUTING.md for development setup, testing, and PR guidelines.
Security
See SECURITY.md for vulnerability reporting.
License
Apache 2.0 — see LICENSE.
