MCP 経由で AI エージェントを接続する

Kozou は MCP サーバーを同梱しており、 PostgreSQL スキーマを AI エージェント向けの構造化されたコンテキストとして公開します。接続すると、Claude Code や Claude Desktop のようなエージェントが、テーブル・ビュー・ビジネス概念が何を意味するか — COMMENT に書いた説明、 @ai ノート、サンプルクエリ — を、6 つの読み取り専用ツールを通じて読み取れるようになります。

このページでは両方のトランスポートを扱います。サーバー自体を起動するローカルエージェント向けの stdio と、Docker やリモート用途向けの HTTP です。コマンドリファレンスは kozou mcp を参照してください。各ツールが返す内容については 3 つの出力面を参照してください。

始める前に

到達可能な PostgreSQL データベースを持つ Kozou プロジェクトが必要です。サーバーは DATABASE_URL 接続文字列を読み取ります — CLI の他の部分が使うのと同じもので、${DATABASE_URL} プレースホルダを通じて kozou.config.yaml に展開されます。一般的な接続文字列は次のようになります。

postgres://USER:PASSWORD@HOST:5432/DBNAME

アプリケーションコードを書く必要はありません。サーバーはスキーマと COMMENT テキストを読み取り、そのまま提供します。

stdio の経路: Claude Code と Claude Desktop

ローカルエージェントの場合、kozou mcp --stdio をクライアントの設定に MCP サーバーとして登録します。エージェントは必要に応じてプロセスを起動し、標準入出力を通じてやり取りします — ポートを待ち受けるものは何もありません。

mcpServers の下にエントリを追加します。この形式は、標準的な設定形式に従う任意の MCP クライアントで動作します（Claude Code と Claude Desktop はどちらも従っています）。

{
  "mcpServers": {
    "kozou": {
      "command": "npx",
      "args": ["-y", "kozou", "mcp", "--stdio"],
      "env": {
        "DATABASE_URL": "postgres://USER:PASSWORD@HOST:5432/DBNAME"
      }
    }
  }
}

このエントリに関するいくつかの注意点です。

npx -y kozou mcp --stdio は、グローバルインストールせずに公開された kozou パッケージを実行します。-y はインストールプロンプトをスキップします。すでに kozou をグローバルにインストールしている場合は、 "command": "kozou" と設定し、args から "kozou" を取り除けます。
DATABASE_URL は、kozou.config.yaml 内の ${DATABASE_URL} プレースホルダを通じて同梱の CLI に読み取られます。クライアントの周囲の環境に頼るのではなく、示したとおり env ブロックに設定してください。
stdio はデフォルトのトランスポートなので、--stdio は明示的ではありますがデフォルトと一致します。サーバーはキャッシュされたスキーマを更新する SIGHUP ハンドラをインストールするため、長時間稼働するプロセスは再起動なしで DDL や COMMENT の変更を取り込めます。

設定を編集したらクライアントを再起動してください。その後、6 つのツールが kozou というサーバー名でエージェントに表示されます。

HTTP の経路: Docker とリモート

コンテナ化された構成やリモート構成の場合は、代わりにサーバーを HTTP で実行します。これは、標準的な MCP クライアントがプロセスを起動するのではなく URL に接続するときに話すトランスポートです。

DATABASE_URL=postgres://USER:PASSWORD@HOST:5432/DBNAME \
  npx kozou mcp --http --port 3334

HTTP サーバーはデフォルトでポート 3334 を待ち受け、MCP エンドポイントを /mcp で提供します。また POST /admin/refresh も公開します。これは stdio の SIGHUP ハンドラに対応する HTTP モードのもので、キャッシュされたスキーマを無効化し、次のリクエストでデータベースを再読み込みさせます。

kozou dev は、この同じ HTTP サーバーを Admin UI と並べて立ち上げます — UI はポート 3333、MCP HTTP サーバーは 3334 で、kozou.config.yaml から配線されます。すでに kozou dev を実行している場合は、別途コマンドを実行しなくても MCP エンドポイントが http://localhost:3334/mcp で有効になっています。kozou dev と Admin UI を生成するを参照してください。

バインドと公開

デフォルトでは、HTTP サーバーは 127.0.0.1（ループバックのみ）にバインドします。リスナーは --host と --port で変更できます。

フラグ	デフォルト	役割
`--port <n>`	`3334`	HTTP サーバーが待ち受ける TCP ポート。
`--host <addr>`	`127.0.0.1`	バインドするインターフェース。

v0.1.1 では、MCP HTTP トランスポートは認証なしで出荷されます。ループバック以外のホストにバインドすると、サーバーは大きな警告を表示します。そのアドレスに到達できる者は誰でもデータベースのスキーマメタデータを読み取れるからです。ツールはスキーマメタデータのみを公開し — SQL の実行もデータアクセスもないため、影響範囲は限定されます — それでも、信頼されたネットワークと外部の認証/プロキシ層の背後に置く場合を除いて、サーバーはループバックに留めておくべきです。

接続後にエージェントができること

サーバーは 6 つのツール、すべて読み取り専用のコンテキストプロバイダを公開します。

ツール	返すもの
`list_tables`	テーブル名と、そのラベル・説明・プランナーによる行数推定。
`describe_table`	1 つのテーブルの完全なスキーマと `COMMENT`: 列、型、NULL 許容性、主キー、外部キー関係、チェック制約。
`list_views`	ビュー名と、そのラベル・目的。
`describe_view`	ビューの列、目的、依存先のテーブル、その SQL 定義。
`list_concepts`	ドメイン概念。それぞれビューに裏付けられています。
`get_concept_context`	概念に関連するテーブル、推奨されるクエリソース、結合の提案、サンプルクエリ。

これらによって、エージェントはスキーマの形だけでなく意味を — そしてそれをクエリする推奨方法を — 読み取ります。describe_table、 describe_view、get_concept_context はそれぞれ、@ai タグで書いた AI 向けノートを携えるため、「売上の数値には、ビュー vw_orders_paid を優先する」といったガイダンスがエージェントに直接届きます。@example で書いたサンプルクエリは、get_concept_context を通じて { description, sql } エントリのリストとして表面化します — 概念に対する推奨クエリ経路です。（これらのタグがどのように解析されるかについては、 COMMENT の規約を参照してください。）

たとえば、orders テーブルについて尋ねられたエージェントは、describe_table を呼び出してその列と外部キーを把握し、次に paid-orders 概念に対して get_concept_context を呼び出して、推奨される FROM ソースとサンプルの売上クエリを見つけます — すべて、プロンプトにスキーマを一切貼り付けることなく。

読み取り専用の安全境界

6 つのツールのいずれも、SQL を生成したり、SQL を実行したり、データを書き込んだりしません。スキーマメタデータと COMMENT テキストを返すだけで、それ以外は何もしません。MCP 経由で Kozou に接続したエージェントは、スキーマが何を意味するかを読み取れますが、この面を通じてデータを変更することはできません — どちらのトランスポートでも、ツールセットに書き込み経路は存在しません。

これはまた、HTTP サーバーがループバックにバインドでき、それ以外では大きく警告する理由でもあります。公開された MCP エンドポイントの最悪のケースは、スキーマメタデータの開示であって、データの損失ではありません。エージェントが行の読み書きを必要とする場合、それは別の面に属します — REST API（v0.1.1 では PostgREST、または v0.2 系列の kozou dev --adapter api の背後にある実験的な自社製 @kozou/api）であって、MCP ではありません。

次に読むもの

kozou mcp — コマンドリファレンス: フラグ、トランスポート、リフレッシュエンドポイント。
COMMENT の規約 — @ai、@example、その他のタグが、エージェントが見る内容をどう形作るか。
3 つの出力面 — MCP コンテキストが Admin UI や REST API とどう並ぶか。