Butterbase: a self-hostable backend-as-a-service with an MCP server bolted to every surface

What Butterbase actually replaces, and for whom

The pitch is a backend you do not have to assemble from separate services. Postgres with row-level security, OAuth and email auth, S3 or R2 file storage, a key-value store with TTL, WebSocket subscriptions, serverless functions, and a managed RAG pipeline all sit behind one API, one dashboard, and one set of service keys. The README frames the target user as someone building AI-driven applications who does not want lock-in, and the topic list names Supabase directly as the comparison point.

The second audience is narrower and more interesting. Because every capability is exposed as MCP tools at `/mcp`, an agent can create a schema, attach an RLS policy, deploy a function and query a table without a human writing glue code. The repository also ships a Claude Code plugin in `packages/plugin` with what the README describes as 30+ guided skills covering idea, plan, schema, auth, functions, deploy and submit. That is a different product from a BaaS with a nice dashboard. It is a BaaS designed to be operated by a model.

Who it is not for: anyone who wants a managed service with a support contract. The README is explicit that this repo is the runtime data plane, and that multi-region orchestration, billing, upstream AI router adapters, lease-based quota enforcement and ops dashboards live in a private repository that consumes this one as a submodule.

The data plane: per-app Postgres, RLS, and an auto-generated REST layer

Each app gets its own database. Schema is declarative and applied through a `/schema` surface, with migrations tracked separately, and an `/auto-api` layer generates REST endpoints from that schema so a table becomes reachable without hand-written route handlers. Row-level security is not an afterthought: the README describes `/rls` as first-class policy management with user-isolation helpers, which suggests the common case (a row belongs to the user who created it) has a shorthand rather than requiring raw policy SQL.

Storage is S3 or R2 backed, with presigned URLs, ACLs and asynchronous indexing. The KV store, marked as new in v0.2.0, is regional and quota-protected, supports TTL, writes an audit trail, and has dashboard expose rules. That last detail matters more than it reads: a KV namespace that can be exposed through the dashboard is a different security posture from one that is only reachable server-side, and the audit trail is the control that makes it defensible.

Realtime is WebSocket subscriptions to table changes, which the README positions for live UIs and presence. Durable Objects are per-key actors, described as suitable for chat rooms, multiplayer, rate limiters and long-running agents. The per-key framing is the constraint to internalise: state is scoped to a key, so anything that needs a global lock or a cross-key transaction is not what this primitive is for.

Compute and AI: Deno functions, an LLM gateway, and RAG as a managed collection

Serverless functions are TypeScript executed on the Deno runtime. That is a deliberate narrowing. Deno's permission model and its npm compatibility story differ from Node's, so a function that depends on a native Node addon is not a drop-in. Edge SSR is a separate surface with `/edge-ssr` and `/edge-ssr-from-source`, and the README names Next.js, Remix and Astro as the frameworks it deploys from source. Frontend hosting accepts a zip or a build from source, with custom domains.

The AI gateway is a single endpoint covering chat, embeddings and model listing, with pluggable router adapters behind `/gateway` and `/ai-config`. The important caveat is in the open-source versus managed section: when you self-host, the gateway runs without upstream router adapters. You get the interface, not the routing. The same applies to billing, which falls back to a no-op provider, and to quotas, which become unlimited. The README tells you to wire your own implementations via the `BillingProvider`, `QuotaEnforcer` and `RouterAdapter` interfaces in `packages/shared`. Treat those three interfaces as the real integration boundary of the project.

RAG is managed: collections, document ingestion, semantic search and synthesized answers under `/rag`. Integrations for third-party tools go through Composio under `/integrations`.

Getting it running: submodules, compose, then a manual migration

The quickstart requires Docker, Node 22 or later, and npm. The first step is not optional in the way it usually is: `packages/plugin` is a git submodule pointing at butterbase-skills, and the README warns that a plain clone leaves it empty and that `npm install` then silently skips that workspace. Clone with `git clone --recurse-submodules https://github.com/butterbase-ai/butterbase.git`, or repair an existing clone with `git submodule update --init --recursive`. There is an optional global setting, `git config --global submodule.recurse true`, to keep submodules current on every pull.

Then `npm ci`, `cp .env.example .env`, and `docker compose -f docker-compose.local.yml up -d`. The README notes that the first run builds images and can take several minutes, and that `docker-compose.local.yml` sets `KV_REDIS_URL_US_EAST_1` for you. You only edit `.env` if you override defaults, for example when running control-api on the host, in which case the Redis URL becomes `redis://localhost:6379`.

Health is checked with `curl -sf http://localhost:4000/health/ready`. The step people will get wrong is the next one: schema is not applied automatically on container start. Migrations run from the repo root with the stack already up, and require environment variables set by hand, including `NEON_PLATFORM_PRIMARY_URL=postgresql://butterbase:butterbase_dev@localhost:5433/butterbase_control` and `NEON_RUNTIME_PROJECT_ID_US_EAST_1`. The README excerpt ends mid-block there, so the full migration procedure has to be read from SETUP.md rather than from the README alone.

Where self-hosting stops being equivalent to the managed product

The gap is not a footnote. Multi-region orchestration is absent, so the multi-region app move script in `scripts/move-app/` relocates an app with retained source replicas but there is no control plane scheduling that for you. Billing is a no-op provider, which means metering, invoicing and plan enforcement do not exist until you write them. Quotas are unlimited, so the quota-protected KV store is protected by nothing by default. Upstream AI router adapters are missing, so failover between model providers is your code against the `RouterAdapter` interface.

There is also no retrieved release history for this repository. The README references v0.2.0 as the version that introduced the KV store, but the material available here lists no releases, so upgrade cadence and breaking-change policy cannot be assessed from what is published. For a project that ships a data plane, that is the single largest unknown: you can read the code, but you cannot yet read a changelog.

The licence is Apache-2.0, which permits commercial use and modification and includes an express patent grant. It does not obligate the maintainers to support you, and it does not cover the private repository holding the managed features. If you fork the runtime and later want the orchestration layer, the licence on this repo gives you no claim on it.

The MCP surface is the differentiator, and also the sharpest edge

Exposing every capability as MCP tools at `/mcp`, with a stdio option via `npx @butterbase/mcp`, is the design decision that separates Butterbase from other self-hosted BaaS projects. A tool that can create tables, write RLS policies and deploy functions is a tool that can also get those things wrong at machine speed. The README does not describe a confirmation step, a dry-run mode, or a policy that limits which MCP tools a given token may call. It lists the surfaces and their paths.

That is a real trade-off rather than a flaw. If you are building agentic applications, having schema and auth as callable tools removes a layer of glue that otherwise has to be written and maintained per project. If you are running a multi-tenant system where a mistaken policy change exposes other users' rows, the same capability is an attack surface, and the mitigation has to come from your deployment: scoped service keys under `/api-keys`, audit logs under `/audit-logs`, and network controls in front of control-api on port 4000. The audit trail described for KV is a starting point, not a complete answer for schema mutations.

Compare this with Supabase, which the repository's own topics name. Supabase's self-hosted stack is a set of separate services (Postgres, GoTrue, PostgREST, Storage, Realtime) that you can adopt one at a time and that have their own release histories and documentation. Butterbase is one API over all of them, which is less to wire up and more to accept as a unit. If you want to replace only the auth layer and keep the rest, Butterbase is the wrong shape. If you want one endpoint, one key model and one MCP server covering everything, the consolidation is the point.

Maintenance cost and what to verify before you commit

Running this means operating Postgres, Redis for KV, an S3 or R2 bucket, the control-api container, and the Deno function runtime, plus whatever you build against the three shared interfaces. The submodule adds a recurring chore: `packages/plugin` tracks butterbase-skills, and a pull that does not recurse leaves the workspace silently incomplete. The `git config --global submodule.recurse true` line in the README exists precisely because that failure is easy to miss.

Upgrades are the open question. With no published releases in the material provided, there is no way to tell whether schema migrations are additive, whether the `/schema` and `/auto-api` contracts are stable, or how the project handles a breaking change to the MCP tool set. Pin to a commit, read SETUP.md and the docs directory before each pull, and check whether the migration step needs new environment variables.

The concrete checks worth doing first: confirm the health endpoint responds after `docker compose -f docker-compose.local.yml up -d`, run the migration block from SETUP.md against your own Postgres rather than the development credentials shown in the README, and read `packages/shared` to see how much of `BillingProvider`, `QuotaEnforcer` and `RouterAdapter` you would be implementing. If those three interfaces look like a week of work rather than a month, the self-hosted path is viable. If they look like a month, the managed offering is doing more of the job than the README's feature list implies.

Editorial conclusion

Adopt Butterbase if you want a Postgres-backed backend whose entire surface is addressable as MCP tools, and you accept that billing, quota enforcement and upstream AI routing are stubs you implement yourself. Do not adopt it if you need a support contract, a published release history, or a managed control plane you did not build. Before committing, verify that `curl -sf http://localhost:4000/health/ready` returns healthy on your hardware, that the migration step in SETUP.md completes against your own Postgres, and that the `BillingProvider`, `QuotaEnforcer` and `RouterAdapter` interfaces in `packages/shared` match what your product needs.

Official sources

1. butterbase-ai/butterbase on GitHub
2. Issues
3. License: Apache-2.0
4. README