デスクトップアプリか、サーバーか
Kozou には 2 つの形があり、混同しやすいものです。本ページはその選択を決めます。
デスクトップアプリは、あなたが「見る」側です。 複数のデータベースのコンパイル済み意味論が 1 つの対話的なビューに並び、その隣に AI が実際に受け取るものが置かれる — そういう場所は他にありません。サーバーは、他のものが「到達する」側です — 手元のマシンからソケットを開けないデータベース、ネットワーク越しの URL しか受け付けないクライアント、二人目、読むだけでなく実行すべきエージェント。
どちらかがもう一方を置き換えるものではなく、両方が欲しい人も多くいます。
それぞれが何であるか
Section titled “それぞれが何であるか”Kozou サーバーは、本サイトの他のページが説明しているものです。開発中の kozou dev、あるいは scaffold されたコンテナ一式を指します。スキーマをコンパイルし、MCP エンドポイントを提供し、リファレンス Admin UI をホストします。置いた場所で動くので、データベースの隣に置くこともできます — 後述するとおり、そこが効いてきます。導入は npm または compose の scaffold から行います。
kozou Desktop は、同じコンパイル済み意味論を、複数のデータベースにまたがる視覚的なマップとして描くデスクトップアプリです。ローカル MCP ハブ (接続プロファイル 1 件につき loopback サーバー 1 つ) を起動して、同じマシン上の AI クライアントに提供することもできます。既定では read-only で、行の閲覧と行の編集はそれぞれ別のプロファイル単位 opt-in です。また experimental です — プレリリースはソースから実行するもので、バイナリは配布していません。今すぐインストールして動かせるものが必要なら、それはサーバー側の経路です。
どちらを使うか
Section titled “どちらを使うか”| これが当てはまるなら | 選ぶもの |
|---|---|
| 複数のデータベースのスキーマを、自分の目で一度に見たい | kozou Desktop |
すでにある COMMENT に対して COMMENT ON 文を書き起こしたい | kozou Desktop |
| データベースが、手元のマシンからソケットを開けない場所にある — VPC の内側、IP 許可制の向こう | データベースの隣に置くサーバー |
| MCP クライアントがネットワーク越しに到達できる URL しか受け付けない | そのクライアントが到達できるサーバー |
| 二人目が同じスキーマ文脈を必要としている | サーバー |
| 呼び出し元を区別する必要がある | auth を設定したサーバー |
| 公開した関数について読むだけでなく、エージェントに実行させたい | 実行を opt-in したサーバー |
実際に決め手になるもの
Section titled “実際に決め手になるもの”最初の 1 つは、デスクトップアプリに手を伸ばす理由のうち、サーバーがまったく答えられない唯一のものです。残りはサーバーが必要になる理由で、うち 3 つ (1・2・5) は関わるのが自分一人でも成立します。サーバーが要ることと、チームがいることは同じではありません。
0. 自分の目で見たいか
Section titled “0. 自分の目で見たいか”デスクトップアプリは、2 つのうち対話的なマップを描く唯一のもので、複数のデータベースを 1 つのビューに置く唯一のものです。AI クライアントが読む describe 出力を人間向けの表示の隣に並べ、COMMENT ON 文を書き起こして渡すこともできます (1 つも実行しません)。
サーバーに対応物はありません。Admin UI は CRUD のリファレンスであってマップではなく、kozou docs が書き出すのは静的な Mermaid の ER 図で、1 プロジェクトずつ Markdown ファイルに出力されます。(ある一点ではその ER 図の方が詳しい表現です — 列と crow’s-foot cardinality を持ちます。デスクトップのマップが示すのはリレーションとその文書化された意味です。)
本ページの中で、サーバー側に答えの無い唯一の因子であり、それゆえ最初に置いています。
1. 手元のマシンからデータベースに到達できるか
Section titled “1. 手元のマシンからデータベースに到達できるか”デスクトップアプリはデータベースに直接接続します — outbound では、その接続がアプリにとって唯一のネットワーク相手です。したがって、手元のマシンからソケットを開けないデータベースは、デスクトップアプリが読めないデータベースであり、設定で変えられるものではありません。(踏み台が該当するのは、そこを通してポートを forward できない場合だけです。forward できるなら、アプリはその URL を他と同じように受け取ります。)
サーバーはデータベースのある場所に置けます — VPC の内側、許可された host の上、同じ境界の向こう側。そのとき境界を越えるのは MCP エンドポイントであって、データベースの認証情報ではありません。
2. クライアントはどの形の接続を必要とするか
Section titled “2. クライアントはどの形の接続を必要とするか”「クライアントが接続できない」の下には、異なる 2 つのケースが隠れています。
- クライアントがローカルのコマンドを起動する、または loopback の URL を受け取る場合 (Claude Code・Claude Desktop・Cursor はこの形で設定します)。どちらの選択肢にも経路があります — デスクトップアプリは自分のハブを指す設定エントリを生成しますし、サーバーには独自の stdio / HTTP 経路があります。決め手になることは稀です。
- クライアントがネットワーク越しに到達できる URL しか受け付けない場合。手元のマシンの loopback に bind されたハブは、その URL ではありません。このケースには、クライアントが到達できる場所にあなたがホストするサーバーが要ります — そのときは無認証の既定ではなく、MCP エンドポイントの
authを伴って。
3. 二人目がいるか
Section titled “3. 二人目がいるか”デスクトップのハブは、同じマシン上の AI クライアントに宛てたものです。アプリは host として 127.0.0.1 を渡しており、それを変える設定はありません。またハブは無認証モードで動きます — プロファイル単位のランダムな capability path と DNS-rebinding guard がローカルでの敷居を上げますが、認証はないので、許可する相手も取り消す相手も存在しません。共有のための設定が足りないのではなく、共有はこのハブの形ではないということです。
複数の呼び出し元を抱えられる形はサーバーの側であり、それらを区別する仕組みが auth です。
4. 呼び出し元を区別する必要があるか
Section titled “4. 呼び出し元を区別する必要があるか”auth を設定したサーバーは呼び出し元を区別します。それによって何が得られるかは、どの面に到達したかで変わります。
- REST は JWT を検証し、各リクエストを
SET LOCAL ROLEの下で実行します。したがって、その呼び出し元が何を読み書きできるかはあなたの RLS ポリシーが決めます。認証と認可を参照してください。 - MCP は token の scope でツール単位に絞ります — describe ツール群に 1 つ、
callにもう 1 つ。describe ツール自体は共有された 1 つのスキーマキャッシュを読むので、describe scope を持つ 2 人の呼び出し元は同じ記述を受け取ります。
デスクトップアプリにはどちらの対応物もありません — MCP サーバーを OAuth のオプションを一切渡さずに構築しています。1 プロファイルは 1 つの保存された接続であり、そのマシン上でハブに到達できるクライアントは、すべて同じものを見ます。
5. エージェントに何かを実行させたいか
Section titled “5. エージェントに何かを実行させたいか”サーバーは、あなたが公開すると決めた関数を実行する call ツールを提供できます — opt-in であり、既定では off です。OAuth なしなら、あなたが設定した固定のサービス role で走ります。OAuth ありなら、代わりに検証された token の role で走り、設定した role は無視されます。RPC アクションを参照してください。
デスクトップアプリのハブは MCP サーバーを実行 capability を渡さずに構築しているため、call はそこでは tools/list に現れず、dispatch もできません。ハブが describe 専用なのは、設定によるものではなく構造によるものです。
手を伸ばしがちだが決め手にならない 4 つ
Section titled “手を伸ばしがちだが決め手にならない 4 つ”- REST。
kozou devは@kozou/apiを127.0.0.1に bind します — ポートは設定できますが host は設定できません — そして scaffold された compose 一式は REST ポートを 1 つも publish しません。そこに残るのは loopback service であって private service ではありません — その loopback を共有するものは届きます。あなた自身のcurlも、そのマシン上のあなた自身のアプリも含めて。authを設定するまで認証はありません。つまり REST はローカル用途にはすでにそこにあり、それ以外の場所に出すのはstartApiServerを使ってあなた自身が動かすことです。どちらにせよ、本ページの選択とは別の判断です。REST API を参照してください。 kozou docs。introspect して file を書き出す one-shot の CLI コマンドです。必要なのは CLI であって、動いているサーバーではありません。- Admin UI と、ラップトップを閉じても動き続けること。どちらもサーバーを動かす実際の理由ですが、弱い理由です — 利便性であって、もう一方を不可能にするものではありません。
- 「どちらが新しいか」。2 つは独立して versioning されており、どちらかがもう一方を置き換えるものではありません。
これはサーバー側の経路が与えるものの網羅リストではありません — 型生成 (@kozou/codegen) にもデスクトップ側の対応物はありません。ここに挙げたのは、この 2 つの間で決めるときに手を伸ばされがちで、かつ決め手にすべきでないものです。
同じことを別の言い方で
Section titled “同じことを別の言い方で”デスクトップアプリは、あなたが意味論を見る場所です — 複数のデータベースを一度に、AI が見ているものをその隣に。サーバーは、それ以外のすべてが意味論に到達する場所です — ソケットを開けないデータベース、あなたの loopback まで来られないクライアント、あなた以外の人、そして読むのではなく動くべきエージェント。