# 最初から最後まで

このサーバーでできることの順序です。各段階で使うツールも一緒に書いています。

## 1. 自分がどこにいるかを確認する

`whoami` が、このトークンが誰のもので、読み取りだけか書き込みもできるかを教えてくれます。
`list_projects` が、プロジェクトとそれぞれのアドレス、そして他のすべてのツールに渡す識別子（ref）を返します。

プロジェクトがなければ `create_project` で作ります。データベース、認証、ファイルストレージが一度に付いてきます。

**リージョンは作成時に一度決めると、後から変更できません。** まず `list_regions` で作成できる場所を確認してください。
空にすると、デフォルトのリージョンに作られます。**料金はリージョンにかかわらず同じなので**、お客様は近い場所を選べば大丈夫です。

`list_regions` の `can_create` が false の場所は、価格までは決まっていますが、まだマシンかデータベースの置き場所がない場所です。
そこに作ろうとすると拒否されます。代わりに `request_region` でリクエストを残してください。
**担当者が直接連絡します。** どこに何を置くつもりかを書いておくと、その内容から読みます。
日付はお約束しません。その間に必要なら、利用可能なリージョンに作って使ってください。後で
移すのではなく、新しく作り直す必要があります。
`list_server_sizes` はサーバーサイズごとのリージョン別月額を返します（通貨を空にすると組織の決済通貨）。読むだけのツールです。

## 2. 今何があるかを確認する

`list_tables` が、テーブルと各テーブルの列、おおよその行数、そして**アクセスルールが有効かどうかとルールの数**を返します。
ルールの数が0のテーブルは、公開キーでは何も見えません。この数が0のテーブルを最初に探してください。

`list_users` は、そのプロジェクトを使う**サービスの登録ユーザー**です。
プラットフォームのアカウント（あなた）とはまったく別のもので、互いに混ざることはありません。
一度にすべては返ってきません。`total` が全体の人数で、`has_more` が true なら `offset` を増やしてもう一度呼び出してください。
**`users` の長さを人数として使うと間違えます。** 人はスクロールバーが止まるのを見ますが、あなたには見えません。

`list_buckets` はファイルストレージ、`usage` は今月の使用量です。

プロジェクトを作った直後は、データベースがまだないことがあります。通常は数秒です。
その間、他のツールは「まだ作成中です」と拒否します。待ってからもう一度呼び出してください。
「作成できませんでした」と出たら、`retry_provisioning` で再試行してください。
**どちらの場合も、プロジェクトを新しく作らないでください。** 同じプロジェクトの準備を続けてください。新しく作ると料金が2倍になるだけです。

使っていないプロジェクトは `pause_project` で一時停止し、`resume_project` で再開します。一時停止中は、サイト、API、関数が 503
（`project_paused`）を返し、定期ジョブは動きませんが、データはそのまま残ります。
無料プランで 3 日間使われずに停止したプロジェクトも、同じく `resume_project`（または新しいデプロイ）で再開します。
データベースを使えない状態（支払いの失敗、無料プラン、一時停止）が 90 日続くと、データベースをサーバーから取り出してアーカイブストレージへ移します。
`list_projects` の `archive_at` が移す日時で、`get_project_archive` が理由と日付を返します。移す 30・7・1 日前にメールが届きます。
移したあと 1 年間は `restore_project_archive` でそのまま復元でき（先にお支払いやプランの問題を解決する必要があります）、`create_archive_download_url` でアーカイブをダウンロードできます。
その間、他のツールは「アーカイブストレージにあります」と拒否し、API は 503（`project_archived`）を返します。1 年が過ぎるとアーカイブとファイルを削除します。
ORM やマイグレーションツール（Prisma、Drizzle、psql）を使うには、`get_database_connection` でアドレスを受け取り、
`reset_database_password` でパスワードを作ってください（表示されるのは1回だけです）。5432 はセッション、6543 はトランザクションのプーラーで、どちらも TLS のみ受け付けます。
デプロイしたアプリが `DATABASE_URL` を読むなら、`keep_for_deploys: true` で作ってください。パスワードを封印して保管し、本番のサーバー・ミドルウェア・関数が実行時に `DATABASE_URL`(6543)・`POSTGRES_URL`(6543)・`DIRECT_URL`(5432) として受け取ります。ビルドには渡しません。デプロイしたコードが行レベルセキュリティを通らずにすべての行を読めるようになるので、ユーザーが望むときだけオンにしてください。このオプションなしで作り直すと受け渡しも止まり、実行中の本番サーバーは再起動か再デプロイで新しい値を受け取ります。
バックアップは毎晩、プロジェクトのリージョンの現地時刻03:00〜05:00に自動で作られます（`list_backups`）。マイグレーションや大量削除の前には、`create_backup` で自分でも作ってください。
`restore_backup` は、テーブル、登録ユーザー、ファイルをその時点に戻します。直前の状態を先にバックアップするので、戻し間違えても再び復元できます。
`delete_project` はデータを**完全に**削除します。ユーザーがはっきり求めたときだけ、`confirm` にプロジェクト名を入れて呼び出してください。

## 3. 作る

テーブルは `run_sql`、ルールも `run_sql`、確認は `read_rows` か `query_sql`。
`query_sql` は読み取り専用トランザクションで照会文を1つだけ実行するため、読み取りトークンでも呼び出せ、データを変更できません。Vault のシークレットの値は開きません。
読み取りトークンには、デプロイフックのアドレス（`list_deploy_hooks`）を隠して返します（`secret_hidden`）。データベースWebhook・ログドレイン・通知チャンネルの署名キーは、トークンに関係なく作成時に一度だけ表示し、一覧には末尾4文字（`signing_secret_last4`）だけを返します。
バケットは `create_bucket`、テスト用の登録ユーザーは `add_user`。
アプリに入れるアドレスとキーは `get_project_keys`。フロントエンドのコードには `only: "publishable"` で受け取ったアドレスと公開キーだけを入れます。

## 接続アドレスのオプション

この接続のアドレスの後ろにオプションを付けると、表示されるツールとできることが絞られます。サーバーが直接守るため、一覧にないツールは名前で呼んでも拒否されます。いま何が有効かは `whoami` の `bound`、`read_only`、`features` でわかります。

- `?project_ref=<ref>`: 接続を1つのプロジェクトに固定します。`ref` を省略するとこのプロジェクトを使い、ほかの ref は拒否します。`list_projects` はこのプロジェクトだけを表示し、ほかのプロジェクトや組織全体に及ぶツール（`create_project`、チーム、通知チャンネル、監査ログ、請求）は外れます。
- `?read_only=true`: 何も変更しないツールだけになります。接続全体が読み取りトークンのように動きます。
- `?features=database,deploy`: 選んだツールのグループだけになります（`whoami` と `list_projects` は常にあります）。グループ: account、database、auth、storage、functions、deploy、domains、branching、logs、billing、ai、realtime、queues、gpu。
- `?lang=ko|en|ja`: ツールの説明とエラーの言語。指定がなければ英語です。

例: `https://<アドレス>/mcp?lang=ja&project_ref=<ref>&read_only=true` は、そのプロジェクトを読むだけの接続です。ユーザーがそれ以上のことを望むなら、オプションを変えて接続し直してもらってください。

## 順序を間違えると起きること

テーブルを作ってルールを作らないと、エラーなしで空の配列が返ってきます。
この1点が、このプラットフォームで起きる問題のほとんどです。blackwall://access-rules を読んでください。

---

https://end.blackall.ai/docs/start?lang=ja