manage_api_keys
List and revoke API keys (service keys) for the Butterbase platform account.
LABSCO SUMMARY
An agent can build and operate a whole backend, not just query one.
Schema, row-level security, functions, storage, realtime and RAG all sit behind the same MCP surface, so the model can provision the thing it needs instead of asking you to open a dashboard first.
What it is
The runtime data plane of Butterbase, an open-source backend-as-a-service. A Fastify control API fronts three Postgres planes, a Deno runtime for serverless functions, S3/R2 storage and a Python agent runtime, and embeds an MCP server at /mcp.
What you get
- Data: per-app Postgres databases with declarative schema and automatic REST endpoints, first-class row-level security policy management, a quota-protected key-value store with TTL and audit trail, and S3/R2-backed file storage with presigned URLs
- Compute: TypeScript serverless functions on the Deno runtime, durable per-key actors for chat rooms and rate limiters, WebSocket subscriptions to table changes, edge SSR for Next.js / Remix / Astro, and static or build-from-source frontend hosting with custom domains
- AI: a single gateway endpoint for chat, embeddings and model listing, plus managed RAG collections with document ingestion, semantic search and synthesized answers
- Identity and ops: email and OAuth sign-in (Google, GitHub, Apple, X), JWT tuning, service keys, structured audit logs and outbound webhooks
- All of it reachable by an agent — the same capabilities are exposed as MCP tools over HTTP at
/mcpor over stdio vianpx @butterbase/mcp
Requirements
Docker, Node 22+ and npm. Clone with --recurse-submodules, because a plain clone leaves packages/plugin/ empty and npm install silently skips that workspace. Then npm ci, cp .env.example .env, and docker compose -f docker-compose.local.yml up -d; the first run builds images and can take several minutes. Schema is not applied on container start — run npm run migrate:all, then npm run seed:dev to create the local dev user. The control API answers on http://localhost:4000 and MCP on http://localhost:4000/mcp. Self-hosting runs the AI gateway without upstream router adapters and with a no-op billing provider; those live in the managed offering, and you wire your own through the BillingProvider, QuotaEnforcer and RouterAdapter interfaces.
Setup effort
Run a container — build the image from the repository, then point your client at it
USE CASES
01
Letting an agent stand up an app backend
Ask for a schema and it lands as a real per-app Postgres database with declarative schema, migrations and automatic REST endpoints — no glue code between the model and the data plane.
02
Getting row-level security right the first time
RLS policy management is a first-class surface with user-isolation helpers, so the isolation rules are written and reviewed as policy rather than reconstructed from application code.
03
Adding retrieval to an app without a separate vector service
Managed RAG collections handle document ingestion, semantic search and synthesized answers inside the same backend that already holds the data.
04
Running it entirely on your own infrastructure
The local Docker Compose profile brings up the control API, three Postgres planes, the Deno runtime, Redis and LocalStack S3 — with AUTH_ENABLED=false for a first smoke test.
05
Keeping long-running agent work alive
Durable Objects give you stateful per-key actors for exactly this — chat rooms, multiplayer state, rate limiters and long-running agents that outlive a single request.
37 tools
Listed in project code.
manage_billing
Manage billing, plans, usage, and spending caps for the Butterbase platform account.
create_frontend_deployment
Create a frontend deployment and get an upload URL.
deploy_function
Deploy or update a serverless function with custom business logic.
butterbase_docs
Read comprehensive Butterbase documentation (local, no API calls).
init_app
Create a new backend app with isolated database and API endpoints.
insert_row
Insert a new row into a table using the auto-generated REST API.
manage_integrations
Manage third-party integrations for a Butterbase app (e.g., Gmail, Slack, Google Calendar).
invoke_function
Invoke a deployed function and return its full HTTP response.
list_partner_apis
List third-party partner APIs (Seedance, Z.AI / 智谱, Qingyun, etc.) configured for a specific Butterbase hackathon.
list_regions
List the regions an app can be created or moved to.
manage_ai
Use the app's AI gateway: chat, embeddings, list models, read/update config, read usage.
manage_app
Manage app lifecycle: list, delete, pause/resume, get config, update access mode, secure, update CORS, clone, and find templates.
manage_auth_config
Manage authentication configuration for an app.
manage_auth_users
Manage end-user auth records for an app.
manage_durable_objects
Manage Durable Object (DO) classes for an app: register/update code, list/get/delete, view usage, and manage shared env vars.
manage_edge_ssr
Manage Edge SSR (Cloudflare Workers) deployments: prebuilt-zip flow, server-side build flow, list history.
manage_frontend
Manage frontend deployments, environment variables, and custom domains for a Butterbase app.
manage_function
Manage function lifecycle: list, delete, get logs, and update environment variables.
manage_kv
Manage app KV store: config rules (expose/unexpose namespaces) and data-plane operations (get/set/del/incr etc).
manage_migrations
Read and control in-flight app migrations.
manage_oauth
Manage OAuth providers for end-user authentication (configure, get, update, delete).
manage_rag_content
Manage RAG (Retrieval-Augmented Generation) collections and documents.
manage_realtime
Manage realtime WebSocket notifications for database tables.
manage_repo
Manage an app's repo (content-addressed code snapshots).
manage_rls
Manage Row-Level Security (RLS): enable on tables, create/update/delete policies, list, and one-shot user isolation setup.
manage_schema
Manage the database schema: read current schema, apply changes, preview changes, and audit migration history.
manage_storage
Manage app storage: presigned upload/download URLs, list/delete objects, update config.
move_app
Migrate an app to a different region.
move_app_status
Get the current status of an app migration.
teardown_source_replica
Tear down the source replica kept after a completed app migration.
query_audit_logs
Query audit events for an app — authentication, admin mutations, and function invocations.
rag_query
Query a RAG collection using natural language to retrieve relevant document chunks.
seed_database
Insert multiple rows into a table in a single call.
select_rows
Query rows from a table using the auto-generated REST API.
prep_and_submit_hackathon_entry
Prep and submit your project to a Butterbase hackathon.
submit_suggestion
Submit feedback, bug reports, or feature suggestions to the Butterbase platform team.
BEFORE YOU INSTALL
What to know first
Tools you get
37 tools registered in the project's code.
Requires
- Docker
- Node 22+ and npm
Optional
BUTTERBASE_API_KEY in your environment
Where it runs
Both documented clients run the server on your machine.
INSTALLATION
Connect your client
Server setup
TERMINAL
git clone --recurse-submodules https://github.com/butterbase-ai/butterbase.git
cd butterbase
npm ci
cp .env.example .env
docker compose -f docker-compose.local.yml up -d
curl -sf http://localhost:4000/health/ready
npm run migrate:all
npm run seed:devMCP Clients
Cursor
CURSOR · JSON
{
"mcpServers": {
"butterbase": {
"url": "http://localhost:4000/mcp",
"headers": {
"Authorization": "Bearer ${env:BUTTERBASE_MCP_TOKEN}"
}
}
}
}Connects to the control API the steps above start. The local Docker Compose profile runs with AUTH_ENABLED=false, so the Authorization header only matters once you enable auth and export BUTTERBASE_MCP_TOKEN with a bb_sk_ key.
Any MCP client — npx
ANY MCP CLIENT — NPX · JSON
{
"mcpServers": {
"butterbase": {
"command": "npx",
"args": [
"-y",
"@butterbase/mcp"
],
"env": {
"BUTTERBASE_API_KEY": "<YOUR_BUTTERBASE_API_KEY>"
}
}
}
}The stdio package talks to http://localhost:4000 by default, so start the stack above first; set CONTROL_API_URL if your control API runs elsewhere. BUTTERBASE_API_KEY is only checked when auth is enabled on your instance — with the local profile you can leave it out.
