# Scribase MCP server: a backend your agent can't wreck

> The Scribase MCP server: schema, RLS, branch and backup tools where every mutation needs explicit confirmation.

Source: https://scribase.com/mcp

44 tools over the hosted endpoint https://api.scribase.com/mcp (control plane: https://api.scribase.com). Every mutating tool refuses without `confirm: true` and returns the exact request it would send. `schema.apply` only accepts a token `policy.test` issued for that exact schema, after proving row-level-security isolation and then breaking each guarantee on purpose to prove the test can fail.

## Schema and policy

Run on a scratch branch owned by the session. schema.apply only accepts a token that policy.test (or policy.simulate) issued for the exact same schema, so an unproven policy cannot be applied.

- `schema.propose` — Parse and plan a schema change without applying it.

- `policy.simulate` — Apply to a scratch branch and run the cross-user isolation matrix. Issues an apply token on pass.

- `policy.test` — The Aegis mutation harness: prove isolation, then break each guarantee on throwaway branches and require every break to be caught. Issues an apply token on pass.

- `schema.apply` (mutation, needs confirm) — Apply a schema that policy.test already proved, using its token.

- `sql.explain` — EXPLAIN a statement against the session branch.

## Branches and previews

Preview environments are TTL-swept branches of production with sanitized data.

- `environment.create` (mutation, needs confirm) — Create an environment, including a preview with a TTL.

- `environment.list` — List environments in a project.

- `environment.get` — Read one environment and its phase.

- `environment.delete` (mutation, needs confirm) — Delete an environment.

- `environment.suspend` (mutation, needs confirm) — Suspend an environment.

- `environment.resume` (mutation, needs confirm) — Resume a suspended environment.

- `branch.register` (mutation, needs confirm) — Register an environment as a branch of a base.

- `branch.list` — List branches and their lineage.

- `branch.diff` — Schema diff between a base and a head environment.

- `branch.merge` (mutation, needs confirm) — Merge a head branch into its base, foreign-key safe.

- `branch.link_pull_request` (mutation, needs confirm) — Link a branch to a GitHub, GitLab, or Bitbucket pull request.

- `operation.get` — Poll an asynchronous operation to a terminal state.

## Data and runtime

Read-only views of a live environment.

- `database.tables` — List tables with row estimates and RLS state.

- `database.query` — Run a read-only SQL query.

- `auth.users` — List auth users (no secrets).

- `storage.buckets` — List storage buckets.

- `functions.list` — List deployed functions.

- `logs.tail` — Tail recent logs.

- `metrics.get` — Read environment metrics.

- `insights.get` — Security and performance advisors.

- `usage.get` — Usage against the plan caps.

## Migrations, backups, and portability

Every write is gated behind confirm and audited.

- `migrate.run` (mutation, needs confirm) — Plan and lint migrations; apply only with apply and confirm.

- `backup.list` — List backups.

- `backup.get` — Read one backup and its verification evidence.

- `backup.create` (mutation, needs confirm) — Take a backup.

- `backup.restore` (mutation, needs confirm) — Restore a backup into a target environment.

- `import.supabase` (mutation, needs confirm) — Dry-run or start a project import in the background.

- `import.status` — Follow a background import: phase, counts, errors, report.

- `export.run` — Produce a portable export bundle.

## Organization and access

Membership and key management.

- `org.list` — List organizations the token can see.

- `org.get` — Read an organization.

- `org.put` (mutation, needs confirm) — Create or update an organization.

- `member.put` (mutation, needs confirm) — Set a member role.

- `project.list` — List projects.

- `project.get` — Read a project.

- `project.put` (mutation, needs confirm) — Create or update a project.

- `apikey.list` — List API keys (never their values).

- `apikey.revoke` (mutation, needs confirm) — Revoke an API key.

- `audit.list` — Read the audit log.

## Connect Claude Code

```bash
claude mcp add --transport http scribase https://api.scribase.com/mcp \
  --header "Authorization: Bearer $SCRIBASE_ACCESS_TOKEN"
```

## Connect Cursor

```json
{
  "mcpServers": {
    "scribase": {
      "url": "https://api.scribase.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:SCRIBASE_ACCESS_TOKEN}"
      }
    }
  }
}
```

## Install the server yourself

```
# Remote: nothing to install. Use the URL below with a personal
# access token (scb_pat_) or organization API key (sbk_).

# Local instead: build the server from the Scribase repository (Rust 1.85+)
cargo install --path crates/mcp

# Over stdio your editor starts it; `scribase-mcp serve --http :8787`
# serves the same tools remotely (needs SCRIBASE_API_URL).
# Schema tools run on a scratch Postgres the server starts itself
# (initdb, pg_ctl and psql on PATH), or on the cluster in PGHOST if set.
# Control-plane tools use SCRIBASE_API_URL and SCRIBASE_ACCESS_TOKEN.
```

## Install the safe-change Claude Code skill

```bash
mkdir -p .claude/skills/scribase-safe-change
curl -fsSL https://scribase.com/mcp/skill -o .claude/skills/scribase-safe-change/SKILL.md
```

## The skill (served verbatim at /mcp/skill)

```markdown
---
name: scribase-safe-change
description: Ship a schema or row-level-security change to a Scribase project safely. Creates a preview branch, applies the migration there, proves RLS isolation with policy.test (the Aegis mutation harness), shows the diff, waits for explicit human confirmation, then merges and cleans up. Use whenever you add or change tables, columns, indexes, functions, or policies on Scribase.
---

# Scribase safe change: preview, test, confirm, merge

Never change production schema directly. Every change goes through this flow,
in order. If any step fails, stop and report; do not skip ahead.

Inputs you need: `ORG`, `PROJECT`, the project `REGION`, a short change
name `CHANGE` (for example `add-invoices`), and the migration files under
`migrations/`.
Credentials come from the environment only (`SCRIBASE_API_URL`,
`SCRIBASE_ACCESS_TOKEN`). Never print them.

## 1. Create a preview branch

A preview is a copy of production with sanitized data and a TTL, so a forgotten
preview deletes itself.

```bash
PREVIEW="preview-$CHANGE"
scribase env create "$ORG" "$PROJECT" "$PREVIEW" preview sanitized "$REGION" "$PREVIEW" 24
scribase operation get "$ORG" "$OPERATION_ID"      # repeat until state is succeeded
scribase branch register "$ORG" "$PROJECT" "$PREVIEW" --base production
```

With the MCP server: `environment.create` (kind `preview`, data mode
`sanitized`, TTL 24), then `operation.get` until it succeeds, then
`branch.register`. Both mutations need `confirm: true`; creating a
preview is safe to confirm yourself because it cannot touch production.

## 2. Apply the migration to the preview only

```bash
scribase migrate "$ORG" "$PROJECT" "$PREVIEW" --dir migrations           # plan + lint
scribase migrate "$ORG" "$PROJECT" "$PREVIEW" --dir migrations --apply   # apply to the preview
```

If the linter blocks a change (a lock-heavy ALTER, a dropped column still in
use), fix the migration. Do not force it.

## 3. Prove row level security

Every table that holds user data must have RLS enabled and policies that keep
user A out of user B's rows.

- MCP: call `policy.test` with the full schema source. It applies the
  schema to a scratch branch, runs the cross-user isolation matrix, then
  breaks each guarantee on purpose (FORCE removed, USING (true), a dropped
  WITH CHECK) on throwaway branches and requires every break to be caught.
  A pass returns an apply token; a failure lists every leak or missed mutant.
- CLI: run Aegis against the preview. `--mutate` breaks each policy on
  purpose and checks the tests notice, which proves the tests can fail.

```bash
aegis compile aegis.yaml
aegis test
aegis test --mutate
scribase insights "$ORG" "$PROJECT" "$PREVIEW"   # advisors: missing RLS, unindexed FKs
```

A single leak or a surviving mutation is a failure. Fix the policies and
return to step 2.

## 4. Show the change and wait for a human

```bash
scribase branch diff "$ORG" "$PROJECT" production "$PREVIEW"
scribase branch merge "$ORG" "$PROJECT" production "$PREVIEW" --dry-run
```

Present, in one message: the schema diff, the merge dry run, the RLS results
(simulate verdict, Aegis pass and mutation score), and any insights findings.
Then stop and ask for explicit approval to merge into production. Do not
treat silence, an earlier approval, or approval of a different change as
consent. With MCP, `branch.merge` without `confirm` returns the exact
request; show it and wait.

## 5. Merge after approval

```bash
scribase backup create "$ORG" "$PROJECT" production "pre-$CHANGE"   # restore point
scribase branch merge "$ORG" "$PROJECT" production "$PREVIEW"
```

With MCP: `backup.create` then `branch.merge` with `confirm: true`, only
after the human approved in step 4. Poll any returned operation with
`operation.get` until it reaches a terminal state. A 202 is not success.

## 6. Clean up and report

```bash
scribase env delete "$ORG" "$PROJECT" "$PREVIEW" "$PREVIEW-delete"
```

Report: the migration files applied, the RLS evidence, the backup id taken
before the merge, and the operation ids. If anything failed after the merge,
say so first and offer `scribase restore start` from the pre-merge backup.

```