# Writbase

> MCP-native task management for AI agent fleets

- **Type:** MCP server
- **Install:** `agentstack add mcp-writbase-writbase`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Writbase](https://agentstack.voostack.com/s/writbase)
- **Installs:** 0
- **Category:** [Databases](https://agentstack.voostack.com/c/databases)
- **Latest version:** 0.1.3
- **License:** Apache-2.0
- **Upstream author:** [Writbase](https://github.com/Writbase)
- **Source:** https://github.com/Writbase/writbase

## Install

```sh
agentstack add mcp-writbase-writbase
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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.

[](LICENSE)
[](https://github.com/Writbase/writbase/actions)
[](https://modelcontextprotocol.io)

---

## 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`:

```bash
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://.supabase.co/functions/v1/mcp-server/mcp
```

> **Prerequisites**: Node 18+, [Supabase CLI](https://supabase.com/docs/guides/cli), a Supabase project ([free tier](https://supabase.com/pricing) works)
>
> Deploy the Edge Function: `npx supabase functions deploy mcp-server --no-verify-jwt`
>
> See the [CLI README](cli/README.md) for all commands.

### Option B: Manual Setup

Clone and deploy manually

```bash
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 
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 dev`
>
> See the [Deployment Guide](docs/deployment.md) 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:

1. **Create a project** — e.g., `my-app`. Optionally add departments (`backend`, `frontend`, `devops`)
2. **Create an agent key** — name it, pick the `worker` role, save the key (`wb__` — shown once)
3. **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

```bash
claude mcp add writbase \
  --transport http \
  --url https://.supabase.co/functions/v1/mcp-server/mcp \
  --header "Authorization: Bearer wb__"
```

Cursor

Add to `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "writbase": {
      "type": "streamableHttp",
      "url": "https://.supabase.co/functions/v1/mcp-server/mcp",
      "headers": { "Authorization": "Bearer wb__" }
    }
  }
}
```

VS Code / Copilot

Add to `.vscode/mcp.json`:

```json
{
  "servers": {
    "writbase": {
      "type": "http",
      "url": "https://.supabase.co/functions/v1/mcp-server/mcp",
      "headers": { "Authorization": "Bearer wb__" }
    }
  }
}
```

Windsurf / Claude Desktop / Other

See the [MCP Config Reference](docs/mcp-config-reference.md) 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](docs/quickstart.md) — 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](https://supabase.com/pricing): 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](docs/deployment.md) for detailed setup instructions.

## Documentation

- [Getting Started](docs/quickstart.md) — Deploy, create an agent key, connect your MCP client, and manage tasks
- [CLI Reference](cli/README.md) — `npx writbase init`, `migrate`, `key`, `status`
- [Deployment Guide](docs/deployment.md) — Supabase Cloud, Vercel, and self-hosted setup
- [Core Concepts](docs/concepts.md) — Permissions, provenance, error codes, delegation
- [MCP Config Reference](docs/mcp-config-reference.md) — Client configs for Claude Code, Cursor, VS Code, Windsurf

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, testing, and PR guidelines.

## Security

See [SECURITY.md](SECURITY.md) for vulnerability reporting.

## License

Apache 2.0 — see [LICENSE](LICENSE).

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Writbase](https://github.com/Writbase)
- **Source:** [Writbase/writbase](https://github.com/Writbase/writbase)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.3 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.3** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-writbase-writbase
- Seller: https://agentstack.voostack.com/s/writbase
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.