@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
npx @backenly/mcp-server init -k <key>
npx @backenly/mcp-server
npx @backenly/mcp-server health
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.