Backenly

@backenly/mcp-server

Backenly を Claude Code、Cursor、Codex、Cline、Claude Desktop に、Model Context Protocol を通じて接続します。

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

エージェントを起動する前に実行してください。ホストは会話の開始時に MCP 設定を読み込むため、ツールが表示されるのはコマンドを実行した会話ではなく、次の会話です。会話の途中でインストールしたエージェントも、npx -y @backenly/cli@latest call <tool> を使って引き続き作業できます。同じキーで同じツールにアクセスできます。

利用できる機能

公開しているツールは 60 個ではなく 23 個です。カタログへの登録は、ただ 1 つのルールに基づく許可リストで管理しています。つまり、あるリクエストに答えるツールがここにちょうど 1 つあるか？ という基準です。カタログが大きくなるほどツール選択の精度は低下し、名前の似たツール間ではモデルが最も誤選択しやすいためです。それ以外のツールには backend_chat 経由でアクセスできます。リストにないツールも引き続き呼び出せるため、古いマニフェストに固定されたクライアントも動作し続けます。

backend_chat — やりたいことを伝える

> Add comments and likes to my posts table

ホストの LLM がリクエストを Backenly の brain に渡します。brain が計画、実行し、要約を返します。ホストの LLM が専用の用語を覚える必要はありません。

読み取り

• 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 — 1 つのテーブルに関するすべての情報を取得します。列、外部キー、インデックス、許可される値を含む 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 から読み戻します。

機能

各ダッシュボードセクションに 1 つのツールがあり、それぞれ 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 — 次のコマンドを 1 つ実行します。

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_ キーはエージェント専用です。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

このパッケージにはビジネスロジックが一切含まれていません — 薄いプロトコルアダプターです。ツール定義、課金、レート制限、監査ログはすべてサーバー側にあります。新しい brain ツールは、npm update なしですぐにホストに表示されます。

プロトコル

公式の MCP TypeScript SDK（v2）を基盤としています。1 つのサーバーで、2 つのプロトコル世代に対応しています。initialize で開始するホスト（リビジョン 2024-11-05 から 2025-11-25）と、2026-07-28（server/discover、リクエストごとの _meta）を使用するホストに対応します。Node.js 20 以降が必要です。

すべてのツールの結果には、サーバーの JSON 本文が 2 回含まれます。フィールド（ok、code、hint、applied、approval、…）を読み取るホスト向けの structuredContent と、テキストのみを読み取るホスト向けのテキストです。失敗時には、次の手順で各フィールドが何を意味するかを説明する 2 つ目のテキストブロックが追加されます。サーバーから送られなかったフィールドは含まれません。

このパッケージが提供するもの（ツール、インストラクション、リソース、結果の形式）は、リモートエンドポイント（https://backenly.com/api/mcp）が提供するものと同じであり、CI で呼び出しごとに比較されます。

信頼性

• 再試行 — ネットワークエラーと 502/503/504 の場合、Retry-After に従い、指数バックオフ（250ms / 1s / 3s + ジッター）で再試行します。
• 起動時のヘルスチェック — マニフェストを取得する前に /api/mcp/health を実行するため、認証エラーが 1 秒未満で表面化します。
• 正常なシャットダウン — SIGINT/SIGTERM でトランスポートを正常に終了し、MCP ホストに破損したフレームが表示されないようにします。
• 相関 ID — 分散トレーシング用に、すべてのリクエストに x-correlation-id が含まれます。

セキュリティ

• MCP キー（mcp_live_…）はスコープで制限されます — /api/mcp/* は runtime SDK キーを拒否します。漏えいした SDK キーを MCP に対して再利用し、テーブルを削除することはできません。
• 破壊的なツールは公開されません。 drop_table、delete_bucket、truncate_table などは、MCP から実行されることはありません。backend_chat で実行を依頼すると、プロジェクトの Review Queue に保留され、承認 ID が返されます。ダッシュボードで人間が判断し、実行または却下されるまで check_approval をポーリングします。エージェント自身が承認することはできません。
• キーごとのレート制限 — ApiKey.rateLimit / rateLimitWindow を使用したスライディングウィンドウ方式です。429 には Retry-After と X-RateLimit-* ヘッダーが含まれます。
• 監査ログ — MCP 経由のすべての変更で、プロジェクトのタイムラインに AuditLog 行が書き込まれます。
• ローカル設定は 0600 の権限（ユーザーのみ読み取り可能）で書き込まれます。
• キーの無効化や、ブラウザーからサインインしたエージェントの接続解除は、 プロジェクトの Connect → Agents ページからいつでも行えます。

環境変数

変数	デフォルト値	備考
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 キーが 1 分あたりの上限に達しました。デフォルトは 600/分です。ダッシュボードから上限を引き上げるか、X-RateLimit-Reset までお待ちください。

ライセンス

MIT — LICENSE を参照してください。