backenly

# Backenly

> Backenly is a backend platform operated by coding agents over MCP or the CLI: PostgreSQL tables in a per-project schema, REST APIs, end-user auth, storage, realtime, functions and third-party integrations. Every change goes through one governed kernel that plans, applies, verifies and journals it; destructive and high-risk changes wait for a human.

This is the index. Each topic below is its own document: fetch one with `fetch_docs { topic: "<topic>" }` or from its URL.

## Connect

A key comes from **project → Connect → Agents**. Register the server in a terminal **before** the conversation starts:

```
claude mcp add backenly -- npx -y @backenly/mcp-server --project <id> --key <scoped-key>
claude mcp add --transport http backenly https://backenly.com/api/mcp --header "x-api-key: <scoped-key>"
```

The remote endpoint also accepts a browser sign-in instead of a key. Other hosts (Codex, Cursor, Cline) are in `client-setup`.

**If the Backenly tools are not in this conversation** (you registered the server during it), do not ask your human to restart. The CLI calls the same tools with the same key and the same governance:

```
npx -y @backenly/cli@latest link --project <id> --key <scoped-key>
npx -y @backenly/cli@latest call read_backend_state
npx -y @backenly/cli@latest chat "add a likes counter to posts"
```

## One project per connection

Every key and OAuth connection is bound to exactly one project. `connect { action: "whoami" }` says which project and which key you are acting as; check it before changing anything when more than one project is in play. Creating or switching projects is done in the dashboard.

## Read before you write

1. `read_backend_state`: what exists.
2. `get_table_schema` on any table you are about to touch.
3. Change it: `apply_migration`, `set_rls`, a section tool, or describe the outcome to `backend_chat`.
4. Read it back, then `generate_types` for the frontend.

## Tools

Exactly **23** tools are advertised; `tools/list` is the authority. Every tool except `backend_chat` and `functions` `create` is deterministic: it runs the call you make, with no model in between.

| Tool | What it is for |
| --- | --- |
| `read_backend_state` | The read door for state. No arguments: the overview. `section` drills in: `schema`, `instructions`, `tables`, `apis`, `buckets`, `files`, `keys`, `users`, `rls`, `triggers`, `functions`, `cron`, `integrations`, `apps`, `env`, `webhooks`, `findings`, `incidents`, `metrics`, `errors`, `usage`, `deploy`, `readiness`, `autonomy`, `maintenance`, `realtime`. |
| `get_table_schema` | One table in full: columns, keys, indexes, CHECK constraints with their permitted values, triggers, RLS policies. |
| `run_query` | Read-only SQL over the project's schema, as a SELECT-only role. |
| `apply_migration` | Schema changes as SQL. Every statement is checked before any runs, and anything it cannot map is refused with the tool to use instead; a statement that fails while running stops the migration, and the response lists what was applied and what remains. |
| `db_insert` / `db_update` / `db_delete` | Row writes as the owner, for seeding and repair. Update and delete need a non-empty filter. |
| `set_rls` | Row-level security as exact SQL predicates, installed verbatim and read back. |
| `generate_types` | TypeScript types, a typed client or OpenAPI from the live catalog. |
| `branch` | Preview branches: `list`, `create`, `diff`, `merge`. |
| `check_approval` | Poll an action waiting for a human. |
| `backend_chat` | Plain-English requests to Backenly's own engine. Draws AI credits. |
| `fetch_docs` | These docs, one topic at a time. |

One tool per dashboard section, each with an `action`:

<!-- generated:section-tools by scripts/generate-agent-docs.ts from lib/mcp/domains.ts; do not edit -->
| Tool | Actions | Docs |
| --- | --- | --- |
| `auth` | `enable`, `add_oauth_provider`, `list_users`, `reset_password`, `unblock_user`, `enable_teams`, `email_settings`, `set_smtp`, `test_smtp`, `set_email_template`, `reset_email_template`; `remove_oauth_provider`, `block_user`, `remove_smtp` wait for approval | https://backenly.com/docs/agents/auth.md |
| `storage` | `create_bucket`, `set_public`, `list_buckets`, `list_files`, `signed_url`; `delete_file`, `delete_bucket` wait for approval | https://backenly.com/docs/agents/storage.md |
| `functions` | `create`, `deploy_code`, `list`, `get`, `invoke`, `logs`, `set_active`, `schedule`, `list_schedules`; `delete`, `delete_schedule` wait for approval | https://backenly.com/docs/agents/functions.md |
| `realtime` | `enable`, `status`; `disable` waits for approval | https://backenly.com/docs/agents/realtime.md |
| `integrations` | `list`, `capabilities`, `verify`, `connect`, `send_push`; `disconnect` waits for approval | https://backenly.com/docs/agents/integrations.md |
| `monitoring` | `metrics`, `errors`, `usage`, `incidents`, `request_logs` | https://backenly.com/docs/agents/monitoring.md |
| `autonomy` | `status`, `findings`, `maintenance`, `set_level` | https://backenly.com/docs/agents/autonomy.md |
| `webhooks` | `list`, `create`, `update`, `test`, `logs`, `replay`, `rotate_secret`, `triggers`, `trigger_deliveries`, `replay_trigger_delivery`, `rotate_trigger_secret`; `delete` waits for approval | https://backenly.com/docs/agents/webhooks.md |
| `deploy` | `status`, `history`, `readiness`; `deploy`, `rollback` wait for approval | https://backenly.com/docs/agents/deploy.md |
| `connect` | `whoami`, `create_api_key`, `list_api_keys`, `set_key_permissions`, `set_env`, `list_env`, `database_credentials`, `connect_frontend`, `list_apps`; `revoke_api_key`, `delete_env`, `disconnect_frontend` wait for approval | https://backenly.com/docs/agents/connect.md |
<!-- end generated -->

## Approvals

An action marked "wait for approval" never runs from the call. The exact call is parked, the response carries an `approval` object with its id, and nothing changes until a human approves it on the project's **Autonomy** page; the approved call then runs verbatim, with no model re-reading it. Dropping or truncating a table and discarding a branch go through `backend_chat`, which parks them the same way. Poll `check_approval` every 15–30 seconds until the status is `executed`, `rejected` (do not retry), `expired`, `failed` (nothing was applied) or `partial` (some changes landed; verify state instead of replaying). Details: `autonomy`.

## Read-only keys

A read-only key or connection sees **16** tools: the read tools, and each section tool narrowed to its read actions. No write action is shown, every write door (`backend_chat`, `apply_migration`, the row writes, `set_rls`, `branch`) is withheld, and a write called anyway is refused with `READ_ONLY_KEY` before it runs. A human chooses read-only when the key is issued; an agent cannot upgrade its own key.

## Keys and headers

- MCP: the key goes in `x-api-key`, or the remote endpoint signs in through the browser.
- Your app's runtime API: `x-api-key: <project key>` on every request, and `X-User-Token: <end-user JWT>` for anything row-level security protects. Do not send the project key as `Authorization: Bearer`: the data API reads that header as an end-user JWT and the request fails with 401.

## Topics

Each is `https://backenly.com/docs/agents/<topic>.md`, or `fetch_docs { topic }`.

- [client-setup](https://backenly.com/docs/agents/client-setup.md): MCP setup per host, the CLI when the tools are not loaded yet, the REST base and headers, the SDK
- [database](https://backenly.com/docs/agents/database.md): reading schema, migrations, row writes, row-level security, types, direct access
- [auth](https://backenly.com/docs/agents/auth.md): sign-up and sign-in for the app you are building, OAuth providers, auth email
- [storage](https://backenly.com/docs/agents/storage.md): buckets, files and signed URLs
- [functions](https://backenly.com/docs/agents/functions.md): server-side code: the two runtime contracts, deploying code you wrote, running it, its logs, schedules
- [realtime](https://backenly.com/docs/agents/realtime.md): table change events over SSE, presence and broadcast
- [integrations](https://backenly.com/docs/agents/integrations.md): connecting provider keys and calling providers from functions
- [stripe](https://backenly.com/docs/agents/stripe.md): payments: connecting, the signed webhook receiver, ctx.integrations.stripe
- [resend](https://backenly.com/docs/agents/resend.md): email: connecting, ctx.integrations.email.send, SendGrid
- [openai](https://backenly.com/docs/agents/openai.md): completions and embeddings from functions
- [anthropic](https://backenly.com/docs/agents/anthropic.md): Claude completions from functions
- [posthog](https://backenly.com/docs/agents/posthog.md): analytics events and feature flags from functions
- [autonomy](https://backenly.com/docs/agents/autonomy.md): the maintenance loop, findings, and how a parked action is approved and polled
- [monitoring](https://backenly.com/docs/agents/monitoring.md): metrics, errors, request logs, usage
- [branches](https://backenly.com/docs/agents/branches.md): preview branches: create, diff, merge (Backenly Cloud)
- [deploy](https://backenly.com/docs/agents/deploy.md): readiness, publishing, history and rollback
- [webhooks](https://backenly.com/docs/agents/webhooks.md): signed outbound endpoints, test deliveries, replays, trigger webhooks
- [connect](https://backenly.com/docs/agents/connect.md): which project a connection acts on, API keys, env variables, database credentials, connected apps
- [errors](https://backenly.com/docs/agents/errors.md): the error shape and the codes an agent should branch on

## Older tool names

Clients pinned to an earlier manifest may hold `list_tables`, `create_table`, `add_column`, `create_index`, `add_rls`, `create_trigger`, `get_backend_metadata`, `get_metrics` and the rest of the pre-consolidation set. They still run by name at `POST /api/mcp/tool` and through the CLI's `call`; they are not advertised because every listed tool costs every agent accuracy.