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

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

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

始める前に

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

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

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

ホスティングされたデータベース(Supabase、Neon、RDS など)に接続しますか? マネージドな PostgreSQL は TLS を必須とします。Kozou は DATABASE_URL をドライバにそのまま渡し、SSL を自動では付与しません。そのため sslmode パラメータを付けないと、サーバーが接続を拒否します。

sslmode=require が通るかどうかは、プロバイダの証明書によります。 公的に信頼された証明書(例: Neon)は、現状 Node 組み込みの CA ストアで検証され、require がそのまま通ります。

postgres://USER:PASSWORD@HOST:PORT/DBNAME?sslmode=require

プライベート CA を提示するプロバイダ(Supabase や AWS RDS など)は、その CA ストアで検証できないため、require は証明書エラーで失敗します。代わりに次のいずれかを使ってください。

# 安全 — プロバイダ自身の CA で検証する(CA はダッシュボードから取得):
postgres://USER:PASSWORD@HOST:PORT/DBNAME?sslmode=verify-full&sslrootcert=/path/to/ca.crt
# 最も簡単 — 証明書を検証せず接続だけ暗号化する(信頼できないネットワークでは避ける):
postgres://USER:PASSWORD@HOST:PORT/DBNAME?sslmode=no-verify

まだデータベースが無いですか? 先にクイックスタートのデモを動かしてください — docker compose up で seeded な PostgreSQL が立ち上がり、このガイドで使える接続文字列 postgres://kozou:kozou@localhost:5432/kozou がそのまま手に入ります。

stdio の経路: Claude Code、Claude Desktop、Cursor

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

mcpServers の下にエントリを追加します。この形式は、標準的な設定形式に従う任意の MCP クライアントで動作します — Claude Code、Claude Desktop、Cursor はいずれも従っています — が、各クライアントで保存場所が異なります（下記の どこに登録するか を参照）。

{
  "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 の変更を取り込めます。

どこに登録するか

上記の JSON は形式であり、各クライアントはそれを異なる場所に保存します。

Claude Code（CLI） — 最も手早いのは claude mcp add で、エントリを自動で書き込みます。

claude mcp add kozou \
  --env DATABASE_URL="postgres://USER:PASSWORD@HOST:5432/DBNAME" \
  -- npx -y kozou mcp --stdio

-- の後はすべてサーバーコマンドとしてそのまま渡されます。--scope project を付けると、個人設定ではなくプロジェクトルートの共有 .mcp.json（チームで git に入れるもの）に書き込まれます。claude mcp list で接続を確認できます（kozou … ✓ Connected と表示されるはずです）。

Claude Desktop — Settings → Developer → Edit Config（ファイルが無ければ作成されます）を開き、mcpServers の下にエントリを追加します。ファイルの場所は次のとおりです。

OS	パス
macOS	`~/Library/Application Support/Claude/claude_desktop_config.json`
Windows	`%APPDATA%\Claude\claude_desktop_config.json`
Linux	`~/.config/Claude/claude_desktop_config.json`

保存後はアプリを完全に終了して開き直してください — 設定は起動時に読み込まれます。開き直すと、メッセージ入力欄の 🔨 ツールアイコンに kozou サーバーとそのツールが表示されるはずです。

Cursor — プロジェクトルートの .cursor/mcp.json（グローバルにする場合は ~/.cursor/mcp.json）にエントリを追加するか、Settings → Features → MCP → Add New MCP Server を使います。編集後は Cursor を再起動してください。その後 Settings → Features → MCP に kozou が緑のドットとツール数とともに表示されます。

その後、7 つのツールが 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 を生成するを参照してください。

クライアントをその URL に向けるには、上記の stdio エントリと同じ要領で、 HTTP 形式で登録します。Claude Code の場合:

claude mcp add --transport http kozou http://localhost:3334/mcp

または claude_desktop_config.json / .cursor/mcp.json を手で編集する場合は、 command / args の代わりに URL 形式を使います。

{
  "mcpServers": {
    "kozou": { "type": "http", "url": "http://localhost:3334/mcp" }
  }
}

バインドと公開

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

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

MCP HTTP トランスポートはデフォルトでは無認証です。ループバック以外のホストにバインドすると、サーバーは大きな警告を表示します。そのアドレスに到達できる者は誰でもデータベースのスキーマメタデータを読み取れるからです。ツールはスキーマメタデータのみを公開し — SQL の実行もデータアクセスもないため、影響範囲は限定されます — それでも、信頼されたネットワークと外部の認証/プロキシ層の背後に置く場合、または OAuth resource-server モード (server.mcp.http.auth) を有効にする場合を除いて、サーバーはループバックに留めておくべきです。後者は毎リクエストにあなた自身の ID プロバイダの検証済み bearer トークンを要求します — リモート MCP と OAuth を参照してください。

試してみる: 違いを見る

kozou のツールが現れたら、答えが列の型ではなくビジネスルールに依存する問いをエージェントに尋ねます。クイックスタートのデモに対して:

kozou のツールを使って、当社の総認識売上はいくらですか? どの行とカラムを除外したか、その理由も説明してください。

Kozou を備えたエージェントは describe_table / get_concept_context を呼び、 vw_recognized_revenue ビューを見つけ、120.00 と答えます — 除外した社内テスト注文と論理削除済みの行を名指しで挙げながら。同じ問いをツールなしで尋ねれば、もっともらしい間違った数字が返ります（デモの当たり前のクエリは 4.8 倍 ずれます）。その対比こそが Kozou の価値です。

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

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

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

これらによって、エージェントはスキーマの形だけでなく意味を — そしてそれをクエリする推奨方法を — 読み取ります。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 ソースとサンプルの売上クエリを見つけます — すべて、プロンプトにスキーマを一切貼り付けることなく。

何に触れてよいかをエージェントに伝える

describe ツールは既定ではスキーマ全体を対象とし、誰が尋ねているかに関係なくすべてのテーブル・列を見せます。Kozou をあるロールに向けてオプトイン (introspection.respectPrivileges: true と role) すると、describe_table / describe_view は各リレーションにそのロールの 実効権限 — テーブルレベルの SELECT / INSERT / UPDATE / DELETE、およびテーブルの列ごとの insertable / updatable — も注記します。これによりエージェントは、試す前に「orders は読めるが書けない」と分かります。施行はするが説明しない query 層には、エージェントへ渡せない差別化です。

Admin UI の権限モードと違い、MCP ツールは隠さずに注記します。ロールが SELECT すらできないテーブルも "select": false とマークされて残るので、エージェントは失敗して気づくのではなく、限界を伝えられ ます。Kozou が既に読み取っている権限を再利用するため追加クエリはなく、内容は advisory のみ — 施行は常に PostgreSQL (ロールの GRANT とあなたの RLS ポリシー) に残ります。kozou docs は同じ情報をテーブルごとの Security セクションとして出力します。オプトインの call 実行ツールを有効にすると、注記されるロールは call が実行されるロールと連動するので、エージェントが伝えられる内容と実際にできることが食い違いません。

テーブルが行フィルタされることをエージェントに伝える

テーブルレベルの権限は「そもそもこのテーブルに触れてよいか」に答えます。行レベルセキュリティ (RLS) はより細かい問い — 「どの行か」「この書き込みは受理される か」 — に答えるもので、Kozou はこれも surface します。describe_table は RLS で保護されたテーブルに rowSecurity シグナルを出します。enabled か、forced か (テーブル所有者にも適用)、ポリシーが 1 つでも存在するか、です。RLS が有効なとき、ツールはプレーンテキストの note を添え、見えている行はフィルタされ得る・書き込みは拒否され得るとエージェントに告げます。これにより、結果を全体だと思い込まなくなります。

このシグナルは既定で ON です。ロール固有の権限ではなくテーブルの構造的事実なので、オプトインは要りません。出力されるのはテーブルのみです — ビュー自身は RLS フラグを持たず、基礎テーブルをマスクするかは security_invoker 次第なので、 Kozou はビューが「フィルタされない」と主張しません。知っておく価値のあるケース: RLS が有効でもポリシーが無いテーブルは default-deny で、所有者以外のロールは何も見えず何も書けません。note はそれも伝えます。

重要な点として、Kozou が読むのは真偽値だけで、ポリシーの式 (USING / WITH CHECK) は決して読みません。これらの述語はあなたの認可モデルそのものを符号化するため、データベース内に留め、エージェントのコンテキストには出しません。テーブルが行フィルタされると知っても、エージェントがフィルタを回避できるわけではありません — 施行は、エージェントが知っているか否かに関わらず PostgreSQL が行います。kozou docs も同じ行をテーブルごとに出力します。

読み取り専用の安全境界

7 つのツールのいずれも、SQL を生成したり、SQL を実行したり、データを書き込んだりしません。スキーマメタデータと COMMENT テキストを返すだけで、それ以外は何もしません — describe_functions は公開された RPC アクションのシグネチャを列挙しますが、アクションの実行は MCP ではなく REST サーフェスに属します。MCP 経由で Kozou に接続したエージェントは、スキーマが何を意味するかを読み取れますが、この面を通じてデータを変更することはできません — どちらのトランスポートでも、ツールセットに書き込み経路は存在しません。

これはまた、HTTP サーバーがループバックにバインドでき、それ以外では大きく警告する理由でもあります。公開された MCP エンドポイントの最悪のケースは、スキーマメタデータの開示であって、データの損失ではありません。エージェントが行の読み書きを必要とする場合、それは別の面に属します — REST API（v1.0 以降は内製の @kozou/api がデフォルト、または kozou dev --adapter postgrest でオプトアウトする外部の PostgREST）であって、MCP ではありません。

本番にエージェントを安全に向ける

爆発半径を小さく保つ 2 つのデプロイ選択があり、上記のシグナルと噛み合います:

introspection をスコープする。 Kozou は向けたスキーマしか見ません。最も機密性の高いテーブルをスコープ外に置けば、エージェントはそれらについて一切推論しません。
広く読み取り中心の可視性を持つロールで接続する。 rowSecurity シグナルはロール非依存なので、接続ロール自身のポリシーが滅多にフィルタしない場合でも、どのテーブルが行フィルタされるかはエージェントに伝わります — 特権的な書き込み経路を渡すことなく、正直なコンテキストを与えられます。

ツールが表示されないとき

接続後にエージェントが kozou のツールを表示しない場合は、次の順に確認してください。

サーバーを手動で起動する。 最も手早い確認は、自分で起動してエラーを読むことです。
Terminal window
```
DATABASE_URL=postgres://USER:PASSWORD@HOST:5432/DBNAME npx -y kozou mcp --stdio
```
起動して標準入力を待つはずです。サーバーはデータベースに 遅延接続 するため、 DATABASE_URL の指す先が誤っていても（ホスト・ポート・認証情報の誤り）、データベースに到達できなくても、起動してツールを列挙します — その問題はここではなく、最初のツール呼び出し時に表面化します（下の「ツールは表示されるが呼び出しが全て失敗する」を参照）。逆にプロセスが即座に終了する場合は、原因はデータベースではなくコマンド・環境・設定です — npx が見つからない、パッケージ名が違う、インストールが壊れている、あるいは設定ファイルの不備（kozou.config.yaml のパースエラー、必須項目の欠落、DATABASE_URL が空/未設定）など。クライアントはサーバーが「失敗した」とだけ報告し理由を示さないので、ここで実際のエラーを読みます。
状態を確認する（Claude Code）。 claude mcp list は各サーバーを接続済みか失敗かで報告し、claude mcp get kozou は解決されたコマンドと環境変数を表示します。
npx には絶対パスを使う。 クライアントが npx を見つけられない場合（spawn ENOENT エラー）、command にフルパスを書きます — which npx で調べられます（例: /usr/local/bin/npx）。
JSON を検証する。 末尾のカンマや引用符の無いキーがあると、設定全体が黙って失敗します。python3 -m json.tool < <設定ファイル> で確認してください。
編集後は再起動する。 Claude Desktop と Cursor は起動時に設定を読み込みます — アプリを完全に終了して開き直してください。Claude Code はセッション開始時に .mcp.json を再読み込みします。
初回実行は遅いことがある。 npx -y は初回実行時にパッケージをダウンロードします。クライアントがタイムアウトする場合は MCP_TIMEOUT=60000 （Claude Code）を設定するか、ダウンロード完了後に開き直してください。

Claude Desktop は各サーバーのログを ~/Library/Logs/Claude/（macOS）または %APPDATA%\Claude\logs\（Windows）に書き込みます — mcp-*.log ファイルにサーバー自身の出力が記録されます。

ツールは表示されるが呼び出しが全て失敗する

kozou のツールは一覧に出るのに、呼び出すと毎回 「Schema is currently unavailable」 が返る場合、サーバーの起動とクライアントとの接続は成功していて、データベースに到達できていないだけです。これは MCP ではなく DATABASE_URL の問題です。ホスト・ポート・認証情報を確認し、ホスト型データベースなら sslmode パラメータ（最も多い原因）も確認してください（上の「始める前に」を参照）。手順 1 のようにサーバーを手動で起動すると、背後の PostgreSQL エラーが標準エラーに出力されます。

次に読むもの

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