Backenly

@backenly/mcp-server

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

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 state
backenly://tables        Table list + counts
backenly://apis          REST endpoints
backenly://buckets       Storage buckets
backenly://triggers      Event triggers
backenly://rls           RLS policies
backenly://functions     AI functions
backenly://deploy        Deploy status
backenly://metrics       Performance metrics
backenly://errors        Recent errors
backenly://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:

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:

{
  "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.

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

Variable	Default	Notes
BACKENLY_API_KEY	from ~/.backenly/mcp.json	Override key (CI / multiple projects).
BACKENLY_API_URL	https://backenly.com	Self-hosted Backenly endpoint.

CLI

npx @backenly/mcp-server init              # interactive setup
npx @backenly/mcp-server init -k <key>     # setup with API key flag
npx @backenly/mcp-server                   # run as MCP server (stdio)
npx @backenly/mcp-server health            # verify the configured key
npx @backenly/mcp-server version
npx @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.