io.github.Writbase/writbase
MCP-native task management for AI agent fleets with scoped permissions and provenance.
Ask AI about io.github.Writbase/writbase
Powered by Claude Β· Grounded in docs
I know everything about io.github.Writbase/writbase. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
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
Clone and deploy manually
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 Code
claude mcp add writbase \
--transport http \
--url https://<project-ref>.supabase.co/functions/v1/mcp-server/mcp \
--header "Authorization: Bearer wb_<key_id>_<secret>"
Cursor
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>" }
}
}
}
VS Code / Copilot
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>" }
}
}
}
Windsurf / Claude Desktop / Other
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
| Agent | Role | Scoped to | Use case |
|---|---|---|---|
ci-bot | worker | my-app/devops β can_create | CI creates tasks on build failure |
triage-agent | worker | my-app (all depts) β can_comment | Reviews tasks, adds notes |
ops-manager | manager | (workspace-wide) | Manages keys, permissions, projects |
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)
| Tool | Description |
|---|---|
info | Agent identity, permissions, and system metadata |
get_tasks | List tasks with filtering, pagination, and full-text search |
add_task | Create a task in permitted scope |
update_task | Update a task with optimistic concurrency control |
Manager Tools (manager agents only)
| Tool | Description |
|---|---|
manage_agent_keys | Create, update, deactivate, rotate agent keys |
manage_agent_permissions | Grant/revoke permissions with subset enforcement |
get_provenance | Query the append-only audit log |
manage_projects | Create, rename, archive projects |
manage_departments | Create, rename, archive departments |
subscribe | Register webhooks for task event notifications |
discover_agents | Find agents by capability and skill |
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
| Supabase Cloud (recommended) | Self-Hosted Supabase | |
|---|---|---|
| Setup | npx writbase init β npx writbase migrate β done | Docker Compose (5 containers) |
| Cost | Free tier: 500MB DB, 50K MAUs | Your infrastructure |
| Dashboard | Deploy to Vercel (free) | Self-host Next.js |
| Updates | Automatic platform updates | Manual |
| Control | Supabase-managed | Full |
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.
