Backenly

io.github.backenlyPublished by GitHub account backenlyv0.4.0Updated Oct 24, 2026

Postgres backend your coding agent builds over MCP; destructive actions wait for a person.

VerifiedStreamable HTTPWeb executableDatabases

Overview

AI-generated overview

Backenly is a remote or local MCP server that lets a coding assistant build and manage a Postgres backend in natural language, with destructive actions held for

What you can do
Describe a change in natural language and Backenly plans, executes and summarizes it. Read backend state, table schemas, REST endpoints, RLS policies, metrics and errors, and run read-only SQL queries. Apply schema migrations, insert or update rows, and set row-level security predicates. Manage auth, storage, functions, realtime, integrations, monitoring, webhooks, deploys and preview branches. Poll escalated destructive requests until a human approves or rejects them.
When to use it
Use it when a coding agent should build and adjust a Postgres backend — tables, RLS, APIs, deploys — without switching to a dashboard by hand. Also suited to teams that want read-only queries and schema inspection while destructive changes still need a person's approval.
Requirements
A Backenly project and a scoped MCP key (BACKENLY_API_KEY, starting with mcp_live_), supplied by environment variable or the local config file the installer writes. Local runs need Node.js 20 or newer and network access to backenly.com or a self-hosted endpoint (BACKENLY_API_URL).
Before you install
The key grants write access to the project; if leaked it can alter the backend, so keep it out of app code and app environments and revoke it when done. Row write tools run at owner level and bypass end-user RLS and triggers. Deploys, rollbacks, deletes and key revocation are parked for human approval and cannot be self-approved by the agent. Every mutation is written to an audit log.

Installation

In SourceWeft

  1. Open Backenly in the dashboard and add it to a workspace.
  2. Connect the required credentials. They are stored privately and never shown on public pages.
  3. Enable the server for the chats that should use its tools.

Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.

Use with an agent

Paste this prompt into Claude Code, Codex, Cursor or another agent — or into SourceWeft chat. The agent reads this server's install guide, shows you its publisher, endpoint and sign-in, and adds it to your client once you agree. Keys never go into a command.

Read https://sourceweft.com/mcp/io.github.backenly%2Fbackenly/install.md and connect the MCP server it describes to my client. Before changing any config, show me its publisher, endpoint and sign-in method and wait for my OK. Never put an API key in a command or in a file I would commit; ask me where it should come from.

Read the install guide the agent follows

Other MCP clients

Add this to your client's mcpServers config. The client completes OAuth sign-in on first connect.

{
  "mcpServers": {
    "backenly": {
      "type": "http",
      "url": "https://backenly.com/api/mcp"
    }
  }
}

README

@backenly/mcp-server

Plug Backenly into Claude Code, Cursor, Codex, Cline, and Claude Desktop over the Model Context Protocol.

sh
claude mcp add backenly -- npx -y @backenly/mcp-server \  --project <projectId> --key mcp_live_...

Run it before you open the agent: hosts read MCP config when a conversation starts, so the tools appear in the next conversation, not the one that ran the command. An agent that installs it mid-conversation keeps working through npx -y @backenly/cli@latest call <tool>, which reaches the same tools with the same key.

What you get

Twenty-three advertised tools, not sixty. The catalog is an allowlist admitted on one rule — is there exactly one tool here that answers a given request? — because tool-selection accuracy degrades with catalog size and models misfire hardest between similarly-named tools. Everything else is reached through backend_chat. Unlisted tools stay dispatchable, so clients pinned to an older manifest keep working.

backend_chat — say what you want

> Add comments and likes to my posts table

The host LLM hands the request to Backenly's brain. Brain plans, executes, and returns a summary. The host LLM never has to learn a vocabulary.

Read

  • read_backend_state — the single read-state door. Call with no arguments for the grounding overview; pass section (schema, tables, apis, rls, metrics, errors, deploy, usage, autonomy, …) to drill in. It replaces the ~26 list_* / get_* tools, which remain dispatchable.
  • run_query — standard read-only SQL over your workspace schema: joins, GROUP BY, aggregates, window functions, CTEs, EXPLAIN. Runs as a SELECT-only Postgres role scoped to the project, so isolation is a database grant rather than a parser. Secret-bearing columns come back redacted.
  • get_table_schema — everything about one table: columns, foreign keys, indexes, CHECK constraints with their permitted values, and live RLS policies. Read it before any write.
  • generate_types — TypeScript types (or a typed client, or OpenAPI) from the live catalog, with a schemaHash for drift checks.
  • fetch_docs — pull current Backenly docs instead of guessing.
  • check_approval — poll an escalated destructive request.

Write

  • apply_migration — ordinary PostgreSQL DDL (CREATE TABLE, ALTER TABLE, CREATE INDEX), translated statement by statement into governed actions. All-or-nothing; anything it cannot govern is refused with the tool to use instead. Not raw SQL execution.
  • db_insert / db_update / db_delete — row writes. Owner-level: validates shapes but bypasses end-user RLS and triggers, so treat them as maintenance tools.
  • set_rls — a row-level security predicate installed verbatim and read back from pg_policies.

Capabilities

One tool per dashboard section, each with an action: auth, storage, functions, realtime, integrations, monitoring, autonomy, webhooks, deploy, connect, plus branch (preview branches). Each tool's description lists its actions and their arguments. Destructive and high-risk actions (deploy, rollback, deletes, revoking a key) park the exact call for a human and run it verbatim once approved; poll check_approval. REST endpoints need no generation step, and older tool names such as enable_auth or adopt_external_schema stay callable by name without being advertised.

Resources (11)

Browse live state without spending a tool call:

backenly://state         Full backend statebackenly://tables        Table list + countsbackenly://apis          REST endpointsbackenly://buckets       Storage bucketsbackenly://triggers      Event triggersbackenly://rls           RLS policiesbackenly://functions     AI functionsbackenly://deploy        Deploy statusbackenly://metrics       Performance metricsbackenly://errors        Recent errorsbackenly://usage         Plan usage

Setup

Generate a scoped key from backenly.com → your project → Connect → Agents. It starts with mcp_live_, only works on MCP routes, and is revocable from the same page.

Claude Code / Codex — one command:

sh
claude mcp add backenly -- npx -y @backenly/mcp-server \  --project <projectId> --key mcp_live_...

Cursor (~/.cursor/mcp.json, not the project's), Cline (cline_mcp_settings.json), Claude Desktop — same server block:

json
{  "mcpServers": {    "backenly": {      "command": "npx",      "args": [        "-y", "@backenly/mcp-server",        "--project", "<projectId>",        "--key", "mcp_live_..."      ]    }  }}

Prefer to keep the key out of a file you might commit? Run the installer once — it verifies the key, writes ~/.backenly/mcp.json (mode 0600), and prints config snippets. The host block then needs no key at all.

sh
npx @backenly/mcp-server init

Open a new conversation in your host. Backenly appears as a tool surface.

The mcp_live_ key is for your agent only. Backenly's runtime API refuses it, so it never goes in app code or an app's environment: the app gets its own key from connect { action: "create_api_key" }, or Settings → API keys.

How it works

Host LLM (Claude Code, Cursor, ...)   │ stdio JSON-RPC   ▼@backenly/mcp-server (this package)   │ HTTPS + x-api-key + x-correlation-id   ▼backenly.com — brain, executor, runtime APIs

The package contains zero business logic — it's a thin protocol adapter. Tool definitions, billing, rate limiting, and audit logging all live server-side. New brain tools appear in your host immediately without npm update.

Protocol

Built on the official MCP TypeScript SDK (v2). It serves both protocol eras from one server: hosts that open with initialize (revisions 2024-11-05 through 2025-11-25) and hosts that speak 2026-07-28 (server/discover, per-request _meta). Requires Node.js 20 or newer.

Every tool result carries the server's JSON body twice: as structuredContent, for hosts that read fields (ok, code, hint, applied, approval, …), and as text, for hosts that only read text. A failure adds a second text block saying what its fields mean for the next step. Fields the server did not send stay absent.

What this package serves (tools, instructions, resources, result shapes) is what the remote endpoint (https://backenly.com/api/mcp) serves, and CI compares the two call for call.

Reliability

  • Retry — network errors and 502/503/504 retry with exponential backoff (250ms / 1s / 3s + jitter), honoring Retry-After.
  • Boot health check — /api/mcp/health runs before manifest fetch so auth failures surface in <1s.
  • Graceful shutdown — SIGINT/SIGTERM close the transport cleanly so MCP hosts don't see corrupt frames.
  • Correlation IDs — every request carries x-correlation-id for distributed tracing.

Security

  • MCP keys (mcp_live_…) are scope-gated — /api/mcp/* rejects runtime SDK keys. A leaked SDK key cannot be replayed against MCP to drop tables.
  • Destructive tools are not exposed. drop_table, delete_bucket, truncate_table, etc. are never executed from MCP. Ask for one via backend_chat and it parks in the project's Review Queue and returns an approval id; a human decides in the dashboard and you poll check_approval until it is executed or rejected. The agent cannot self-approve.
  • Per-key rate limit — sliding-window using ApiKey.rateLimit / rateLimitWindow. 429 includes Retry-After + X-RateLimit-* headers.
  • Audit log — every mutation through MCP writes an AuditLog row on your project timeline.
  • Local config is written with 0600 permissions (user-only readable).
  • Revoke any key, or disconnect an agent you signed in from the browser, anytime from your project's Connect → Agents page.

Environment

VariableDefaultNotes
BACKENLY_API_KEYfrom ~/.backenly/mcp.jsonOverride key (CI / multiple projects).
BACKENLY_API_URLhttps://backenly.comSelf-hosted Backenly endpoint.

CLI

sh
npx @backenly/mcp-server init              # interactive setupnpx @backenly/mcp-server init -k <key>     # setup with API key flagnpx @backenly/mcp-server                   # run as MCP server (stdio)npx @backenly/mcp-server health            # verify the configured keynpx @backenly/mcp-server versionnpx @backenly/mcp-server help

Troubleshooting

"This key has scope='runtime'" — you pasted your SDK anon key. Generate a separate MCP key from the project's Connect → Agents page.

"Could not reach Backenly" — check your internet or set BACKENLY_API_URL if self-hosting.

Host shows "MCP server crashed" — run npx @backenly/mcp-server health to verify the key. Check ~/.backenly/mcp.json exists and has mode 0600.

Rate-limited (429) — your MCP key hit its per-minute cap. Default is 600/min; raise it from the dashboard or wait until X-RateLimit-Reset.

License

MIT — see LICENSE.

Source: packages/mcp-server/README.md at commit 08671c7

Tools

0
This server asks you to sign in, so SourceWeft could not read its tools without an account and has not indexed them. What a connected account sees can depend on that account and its permissions.

Version history

1
  1. v0.4.0LatestOct 24, 2026

Score

85% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 daysRequired25 pts
  • Auth declaredRequired10 pts
  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts