Backenly

@backenly/mcp-server

通过 Model Context Protocol，将 Backenly 接入 Claude Code、Cursor、Codex、Cline 和 Claude Desktop。

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

请在打开 Agent 前运行它：宿主会在对话开始时读取 MCP 配置，因此工具会出现在下一次对话中，而不是运行命令的那次对话中。在对话中途安装它的 Agent 可以继续通过 npx -y @backenly/cli@latest call <tool> 工作，该命令会使用相同的密钥调用相同的工具。

你将获得什么

目录中列出的是 23 个工具，而不是 60 个。工具目录采用白名单机制，筛选规则只有一条——这里是否恰好有一个工具能回答给定请求？——因为工具数量增加会降低工具选择准确度，而模型在名称相似的工具之间最容易选错。其他所有工具都可通过 backend_chat 调用。未列出的工具仍可调度，因此固定使用较旧清单的客户端仍能正常工作。

backend_chat — 直接说出你的需求

> Add comments and likes to my posts table

宿主大模型会将请求交给 Backenly 的大脑。大脑负责规划、执行并返回摘要。宿主大模型无需学习一套专门的术语。

读取

• read_backend_state — 读取状态的统一入口。不带参数调用可获取基础概览；传入 section（schema、tables、apis、rls、metrics、errors、deploy、usage、autonomy 等）可深入查看。它取代了约 26 个 list_* / get_* 工具；这些工具仍可调度。
• run_query — 对工作区架构执行标准的只读 SQL 查询：连接、GROUP BY、聚合、窗口函数、CTE、EXPLAIN。查询以仅允许 SELECT 的 Postgres 角色运行，并限定在项目范围内，因此隔离由数据库授权保障，而非依赖解析器。包含机密信息的列会以脱敏形式返回。
• get_table_schema — 查看单个表的所有信息：列、外键、索引、含允许值的 CHECK 约束，以及当前的 RLS 策略。执行任何写入前请先读取。
• generate_types — 根据当前目录生成 TypeScript 类型（或类型化客户端、OpenAPI），并提供用于检测偏差的 schemaHash。
• fetch_docs — 获取最新的 Backenly 文档，避免凭猜测操作。
• check_approval — 轮询已升级处理的破坏性请求。

写入

• apply_migration — 常规 PostgreSQL DDL（CREATE TABLE、ALTER TABLE、CREATE INDEX）会逐条语句转换为受治理的操作。要么全部执行，要么全部不执行；无法治理的内容会被拒绝，并告知应使用的工具。此工具不执行原始 SQL。
• db_insert / db_update / db_delete — 行写入。具有所有者级权限：会验证数据结构，但绕过终端用户 RLS 和触发器，因此应将其视为维护工具。
• set_rls — 原样安装行级安全谓词，并从 pg_policies 中读取确认。

功能

每个仪表板分区对应一个工具，每个工具都带有 action：auth、storage、functions、realtime、integrations、monitoring、autonomy、webhooks、deploy、connect，以及用于预览分支的 branch。每个工具的说明都会列出其操作及参数。破坏性和高风险操作（部署、回滚、删除、撤销密钥）会将原始调用完整保留，交由人工审批；获批后再原样执行；请轮询 check_approval。REST 端点无需生成步骤；enable_auth 或 adopt_external_schema 等旧工具名称仍可按名称调用，但不会列入目录。

资源（11 个）

无需消耗工具调用，即可浏览实时状态：

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

设置

从 backenly.com → 您的项目 → Connect → Agents 生成一个限定范围的密钥。它以 mcp_live_ 开头，仅适用于 MCP 路由，也可在同一页面撤销。

Claude Code / Codex — 运行一条命令：

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

Cursor（~/.cursor/mcp.json，而非项目中的文件）、Cline（cline_mcp_settings.json）、Claude Desktop — 使用相同的服务配置块：

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

想避免将密钥存入可能提交的文件？运行一次安装程序即可—— 它会验证密钥、写入 ~/.backenly/mcp.json（权限模式为 0600），并打印配置片段。 这样，主机配置块就完全不需要密钥。

npx @backenly/mcp-server init

在主机中开启新的对话。Backenly 会作为工具界面出现。

mcp_live_ 密钥仅供您的 Agent 使用。Backenly 的运行时 API 会拒绝该密钥， 因此它绝不会出现在应用代码或应用环境中：应用应通过 connect { action: "create_api_key" } 或 Settings → API keys 获取自己的密钥。

工作原理

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

该软件包不包含任何业务逻辑——它只是一个轻量级协议适配器。工具定义、计费、速率限制和审计日志都在服务端处理。新工具一经发布，就会立即出现在您的主机中，无需运行 npm update。

协议

基于官方 MCP TypeScript SDK（v2）构建。一个服务即可支持两个协议时期：使用 initialize 启动的主机（版本从 2024-11-05 到 2025-11-25），以及使用 2026-07-28 协议的主机（server/discover、每个请求的 _meta）。需要 Node.js 20 或更高版本。

每个工具结果都会携带两份服务端 JSON 正文：一份作为 structuredContent，供读取字段的主机使用（ok、code、hint、applied、approval 等）；另一份作为文本，供只读取文本的主机使用。失败时还会添加第二个文本块，说明这些字段对下一步操作的含义。服务端未发送的字段会保持缺省。

本软件包提供的内容（工具、说明、资源、结果格式）与远程端点（https://backenly.com/api/mcp）提供的内容一致，CI 会逐一比较两者的调用。

可靠性

• 重试 — 网络错误和 502/503/504 会按指数退避策略重试（250ms / 1s / 3s + 随机抖动），并遵循 Retry-After。
• 启动健康检查 — 获取清单前会先运行 /api/mcp/health，确保身份验证失败能在 <1s 内显现。
• 平滑关闭 — SIGINT/SIGTERM 会干净地关闭传输，避免 MCP 主机看到损坏的数据帧。
• 关联 ID — 每个请求都携带 x-correlation-id，用于分布式追踪。

安全

• MCP 密钥（mcp_live_…）受范围限制——/api/mcp/* 会拒绝 runtime SDK 密钥。泄露的 SDK 密钥无法被重放到 MCP，以删除数据表。
• 不会公开破坏性工具。 MCP 永远不会执行 drop_table、delete_bucket、truncate_table 等操作。通过 backend_chat 请求此类操作后，操作会进入项目的 Review Queue 并返回审批 ID；由人工在仪表板中决定，然后您可以轮询 check_approval，直到操作执行或被拒绝。Agent 无法自行审批。
• 每个密钥的速率限制 — 使用 ApiKey.rateLimit / rateLimitWindow 实现滑动窗口限流。429 响应包含 Retry-After + X-RateLimit-* 标头。
• 审计日志 — 通过 MCP 执行的每次变更都会在项目时间线上写入一条 AuditLog 记录。
• 本地配置以 0600 权限写入（仅用户可读）。
• 您可以随时在项目的 Connect → Agents 页面撤销任意密钥，或断开通过浏览器登录的 Agent。

环境

变量	默认值	备注
BACKENLY_API_KEY	来自 ~/.backenly/mcp.json	覆盖密钥（CI / 多个项目）。
BACKENLY_API_URL	https://backenly.com	可自托管的 Backenly 端点。

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

故障排除

“This key has scope='runtime'” — 你粘贴的是 SDK 匿名密钥。请从项目的 Connect → Agents 页面生成单独的 MCP 密钥。

“Could not reach Backenly” — 请检查网络连接；如果是自托管，请设置 BACKENLY_API_URL。

主机显示 “MCP server crashed” — 运行 npx @backenly/mcp-server health 验证密钥。检查 ~/.backenly/mcp.json 是否存在且权限模式为 0600。

遭遇速率限制（429） — 你的 MCP 密钥已达到每分钟请求上限。默认上限为 600 次/分钟；请在控制面板中提高上限，或等到 X-RateLimit-Reset 指定的时间。

许可证

MIT — 参见 LICENSE。