エージェント統合に AlloyDB Omni と MCP ツールボックスを使用する

1. はじめに

Antigravity CLI などの AI エージェントにデータベースへの安全で構造化されたアクセス権を付与するには、AlloyDB Omni をデータベース向け MCP ツールボックスと統合します。

AlloyDB Omni は、AlloyDB for PostgreSQL のダウンロード可能なコンテナ化されたエディションです。オンプレミス、デベロッパー ワークステーション、エッジ、クラウドなど、どこでも実行できるように設計されており、エンタープライズ グレードの PostgreSQL のパフォーマンスと互換性を実現します。

データベース向け MCP ツールボックスは、Model Context Protocol（MCP）を実装した Google のオープンソース サーバーです。これにより、データベースとやり取りする生成 AI ツールをより簡単、迅速、安全に構築できます。エージェントのオーケストレーション フレームワークとデータベースの間に位置し、次の機能を提供します。

  • 簡素化された開発: 最小限の構成でエージェントに接続し、複数のエージェントやフレームワークで再利用できる、事前構築済みまたはカスタムのデータベース ツール。
  • パフォーマンスの向上: 接続プーリングやライフサイクル管理などのベスト プラクティスが組み込まれています。
  • セキュリティの強化: 認証情報と認証を一元管理するため、エージェントは未加工のデータベース認証情報を必要としません。
  • エンドツーエンドのオブザーバビリティ: OpenTelemetry の組み込みサポートによる、すぐに使える指標とトレース。

この Codelab を完了すると、サンプルの e コマースデータが入力された AlloyDB Omni コンテナ、31 個の事前構築済みの AlloyDB Omni 管理ツールとクエリツールを公開する MCP ツールボックス サーバー、自然言語プロンプトを使用してスキーマの検査、SQL クエリの実行、クエリプランの分析、データベースの健全性の診断を行うことができる構成済みの Antigravity CLI（agy）エージェントが実行されます。

エージェントから MCP クライアント（Antigravity CLI）、MCP ツールボックス、AlloyDB Omni へのエンドツーエンドのワークフローを示すアーキテクチャ図

前提条件

  • Google Cloud コンソールまたは Linux ワークステーションから Google Cloud プロジェクトと Cloud Shell にアクセスできる。
  • Docker がインストールされ、実行されている。
  • psql PostgreSQL クライアントがインストールされている。
  • curl と jq がインストールされている。これらは、Antigravity CLI と MCP ツールボックスを設定するために必要です。

学習内容

  • Docker を使用して AlloyDB Omni データベース サーバー コンテナをデプロイして実行する方法。
  • AlloyDB Omni でサンプル テーブル、データ、インデックスを作成する方法。
  • 事前構築済みの alloydb-omni ツールセットを使用して、データベース向け MCP ツールボックスをダウンロード、構成、起動する方法。
  • Antigravity CLI を MCP クライアントとして構成し、MCP ツールボックス サーバーに接続する方法。
  • Antigravity CLI で自然言語プロンプトを使用して、データベースの健全性の検査、スキーマの探索、SQL クエリの実行、クエリプランの分析、メンテナンス診断を行う方法。

必要なもの

  • Docker、psql、curl、jq を含む、動作するターミナル環境。これらのツールがプリインストールされている Google Cloud Shell を使用することもできます。

2. 設定と要件

プロジェクトの設定

Google Cloud プロジェクトを作成する

  1. Google Cloud コンソールのプロジェクト セレクタ ページで、Google Cloud プロジェクトを選択または作成します。
  2. Google Cloud プロジェクトで課金が有効になっていることを確認します。プロジェクトで課金が有効になっているかどうかを確認する方法をご覧ください。

Cloud Shell の起動

AlloyDB Omni と MCP ツールボックスはノートパソコンでローカルに実行できますが、この Codelab では、Docker、psql、curl、jq がプリインストールされたクラウドで動作するコマンドライン環境である Google Cloud Shell を使用します。

Cloud Shell をアクティブにするアイコン

  1. Google Cloud コンソールを開き、右上のツールバーにある [Cloud Shell をアクティブにする] をクリックします。次のいずれかの方法で Cloud Shell を開くこともできます。
    • Google Cloud コンソールを使用している場合は、G、S の順に押します。
    • Cloud Shell を直接開きます。

通常、環境がプロビジョニングされ、接続されるまでしばらく待ちます。このオペレーションが完了すると、次のようなメッセージが表示されます。

環境が接続されていることを示す Google Cloud Shell ターミナル

3. AlloyDB Omni データベース サーバーを準備して実行する

このセクションでは、AlloyDB Omni Docker コンテナを pull して実行し、テスト用のサンプル e コマース データを入力します。

AlloyDB Omni データベース サーバーを起動する

  1. AlloyDB Omni ホスト、ポート、データベース、ユーザー、生成されたパスワードの環境変数を定義します。
    export ALLOYDB_OMNI_HOST="127.0.0.1"
export ALLOYDB_OMNI_PORT="5432"
export ALLOYDB_OMNI_DATABASE="postgres"
export ALLOYDB_OMNI_USER="postgres"
export ALLOYDB_OMNI_PASSWORD="$(openssl rand -hex 8)@1aA"
echo "Your generated AlloyDB Omni postgres password is: $ALLOYDB_OMNI_PASSWORD"
  2. Docker を使用して、AlloyDB Omni コンテナをデタッチモードで起動します。
    docker run --name alloydbomni \
    -e POSTGRES_PASSWORD=$ALLOYDB_OMNI_PASSWORD \
    -p $ALLOYDB_OMNI_PORT:$ALLOYDB_OMNI_PORT \
    -d google/alloydbomni:latest
  3. コンテナが実行されていること、psql を使用して AlloyDB Omni サーバーに接続できることを確認します。
    docker ps -a
until docker exec alloydbomni pg_isready -U "$ALLOYDB_OMNI_USER" -d "$ALLOYDB_OMNI_DATABASE"; do sleep 2; done
PGPASSWORD=$ALLOYDB_OMNI_PASSWORD psql -h $ALLOYDB_OMNI_HOST -p $ALLOYDB_OMNI_PORT -U $ALLOYDB_OMNI_USER -d $ALLOYDB_OMNI_DATABASE -c "SELECT 1;"

テスト用のサンプルデータを作成する

サンプルの categories、products、customers、orders テーブルを作成し、テストレコードを挿入して、インデックスを作成します。これにより、MCP ツールボックスを介してスキーマ検査、SQL クエリ、クエリ実行プランをテストできます。

PGPASSWORD="$ALLOYDB_OMNI_PASSWORD" psql -h $ALLOYDB_OMNI_HOST -p $ALLOYDB_OMNI_PORT -U $ALLOYDB_OMNI_USER -d $ALLOYDB_OMNI_DATABASE << 'EOF'
CREATE TABLE IF NOT EXISTS categories (
    category_id SERIAL PRIMARY KEY,
    name VARCHAR(50) UNIQUE NOT NULL
);

CREATE TABLE IF NOT EXISTS products (
    product_id SERIAL PRIMARY KEY,
    product_name VARCHAR(100) UNIQUE NOT NULL,
    category VARCHAR(50) NOT NULL,
    price NUMERIC(10, 2) NOT NULL,
    stock INT DEFAULT 0
);

CREATE TABLE IF NOT EXISTS customers (
    customer_id SERIAL PRIMARY KEY,
    first_name VARCHAR(50),
    last_name VARCHAR(50),
    email VARCHAR(100) UNIQUE,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

CREATE TABLE IF NOT EXISTS orders (
    order_id SERIAL PRIMARY KEY,
    customer_id INT REFERENCES customers(customer_id),
    order_date TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    total_amount NUMERIC(10, 2)
);

-- Insert sample rows
INSERT INTO categories (name) VALUES
('Smartphones'),
('Laptops'),
('Audio')
ON CONFLICT DO NOTHING;

INSERT INTO products (product_name, category, price, stock) VALUES
('Pixel 9 Pro', 'Smartphones', 999.00, 50),
('MacBook Pro M3', 'Laptops', 1999.00, 20),
('ThinkPad X1 Carbon', 'Laptops', 1450.00, 35),
('Dell XPS 15', 'Laptops', 1700.00, 15),
('Bose QuietComfort', 'Audio', 349.00, 100)
ON CONFLICT DO NOTHING;

INSERT INTO customers (first_name, last_name, email) VALUES
('Ada', 'Lovelace', 'ada@example.com'),
('Alan', 'Turing', 'alan@example.com'),
('Grace', 'Hopper', 'grace@example.com')
ON CONFLICT DO NOTHING;

INSERT INTO orders (order_id, customer_id, total_amount, order_date) VALUES
(1, 1, 999.00, pg_catalog.now() - INTERVAL '7 months'),
(2, 2, 349.00, pg_catalog.now() - INTERVAL '1 month')
ON CONFLICT DO NOTHING;

CREATE INDEX IF NOT EXISTS idx_products_category ON products(category);
CREATE INDEX IF NOT EXISTS idx_orders_customer ON orders(customer_id);
EOF

4. MCP ツールボックス サーバーを起動する

このセクションでは、MCP ツールボックス バイナリをダウンロードし、事前構築済みの AlloyDB Omni ツール定義を構成して、MCP ツールボックス サーバーを起動します。

MCP ツールボックスをダウンロードする

  1. MCP ツールボックスのディレクトリを作成し、toolbox バイナリをダウンロードします。
    mkdir -p ~/mcp/tools
cd ~/mcp
curl -L -O https://storage.googleapis.com/genai-toolbox/v0.31.0/linux/amd64/toolbox
chmod +x toolbox
./toolbox --version

MCP ツールボックス サーバーを構成して起動する

  1. 事前ビルドされた alloydb-omni.yaml ツール構成をダウンロードし、ポート 5000 で MCP ツールボックス サーバーを起動します（先ほどエクスポートした ALLOYDB_OMNI_* 環境変数を使用）。
    curl -sL --create-dirs -o "tools/alloydb-omni.yaml" "https://raw.githubusercontent.com/googleapis/mcp-toolbox/v0.31.0/internal/prebuiltconfigs/tools/alloydb-omni.yaml"
# Remove the trailing group definition block and YAML document separator for --config-folder compatibility
sed -i '/^kind: group/,$d' tools/alloydb-omni.yaml
sed -i '${/---/d;}' tools/alloydb-omni.yaml

./toolbox --config-folder ./tools/ --port 5000 --address 127.0.0.1
    alloydb-omni.yaml 構成には、この Codelab で紹介した主要なツールを含む 31 個の事前構築済みツールが用意されています。
    • execute_sql
    • get_query_plan
    • database_overview
    • list_active_queries
    • list_tables、list_indexes、list_views、list_triggers
    • list_top_bloated_tables、list_locks、list_autovacuum_configurations、list_invalid_indexes
    ツールの完全なリストについては、GitHub の alloydb-omni.yaml をご覧ください。
  2. 新しいターミナルタブで、MCP ツールボックス サーバーが実行されており、JSON-RPC /mcp エンドポイントを介してツールが公開されていることを確認します。
    curl -X POST http://localhost:5000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}'

5. MCP クライアント（Antigravity CLI）を構成する

このセクションでは、Antigravity CLI（agy）をインストールし、MCP ツールボックス サーバーに接続するように構成します。

Antigravity CLI をインストールする

  1. まだインストールされていない場合は、Antigravity CLI（agy）インストーラをダウンロードして実行し、バージョンを確認します。
    curl -fsSL https://antigravity.google/cli/install.sh -o /tmp/install.sh
bash /tmp/install.sh
rm -f /tmp/install.sh

# If prompted by the installer, add ~/.local/bin to your PATH:
export PATH="$HOME/.local/bin:$PATH"

# Verify the installation
agy --version

Antigravity CLI を構成する

クライアントの MCP 構成ファイル（Antigravity CLI の場合は ~/.gemini/config/mcp_config.json、Claude Code の場合は .cursor/mcp.json、.vscode/mcp.json、claude_desktop_config.json、.mcp.json など）に MCP Toolbox サーバーのエントリを追加します。

  1. Antigravity CLI をポート 5000 で実行されている MCP ツールボックス HTTP サーバーに接続するには、agy mcp add を実行し、agy mcp list でエントリを確認します。
    export MCP_SERVER="127.0.0.1"
export MCP_PORT="5000"

agy mcp add alloydb-omni "http://${MCP_SERVER}:${MCP_PORT}/mcp"
agy mcp list
    これにより、alloydb-omni サーバー構成が ~/.gemini/config/mcp_config.json に書き込まれます。
    {
  "mcpServers": {
    "alloydb-omni": {
      "url": "http://127.0.0.1:5000/mcp"
    }
  }
}

構成を確認する

  1. Antigravity CLI を起動します。
    agy
    agy を初めて起動する場合は、画面上の指示に沿ってログインし（Google OAuth または Google Cloud プロジェクトを使用）、現在のディレクトリを信頼するかどうかを尋ねられたら [Yes, I trust this folder] を選択します。
  2. Antigravity CLI プロンプトで /mcp と入力して [MCP サーバー] パネルを開き、alloydb-omni が接続されていることを確認します。
    /mcp
    出力は次のようになります。
    MCP Servers

Configured (~/.gemini/config/mcp_config.json)
>  ✓ alloydb-omni  Tools: database_overview, execute_sql, get_column_cardinality, get_query_plan, list_active_queries, +26 more

Keyboard: ↑/↓ Navigate  enter Actions
  3. Esc を押して [MCP Servers] パネルを閉じ、Antigravity CLI プロンプトに戻ります。

6. AlloyDB Omni のクエリを使用してテストする

Antigravity CLI が MCP ツールボックスを介して AlloyDB Omni インスタンスに接続されたので、自然言語プロンプトを使用してデータベースを操作できます。

データベースの概要クエリを実行する

  1. Antigravity CLI プロンプトで、現在のデータベースの概要を尋ねます。
    Give me an overview of the current database.
    ツールの呼び出しを許可するよう求められたら、[はい]（または、この会話では [はい、常に許可する]）を選択します。出力は次のようになります。
    > Give me an overview of the current database.

● alloydb-omni/database_overview(Database overview check) (ctrl+o to expand)

  Here is an overview of the current AlloyDB Omni database instance:

  ### Database Overview
  • Instance / Engine: PostgreSQL 17.9 (AlloyDB Omni)
  • Role: Primary (is_replica: false)
  • Uptime: ~7 hours, 57 minutes
  • Connected Database: postgres
  • Connected User: postgres
  • Connections: 11 current / 100 max (1 active, 11% used)

  ### Databases in Instance
  • postgres
  • alloydbadmin (~15.74 MB)
  • alloydbmetadata (~14.82 MB)

カテゴリ別のテスト例

Antigravity CLI に次の自然言語リクエストを送信します。エージェントは、各リクエストを AlloyDB Omni MCP ツールセットの対応するツールに自動的にマッピングします。

1. データベースの概要と健全性

テスト目標

自然言語プロンプト

ツールが呼び出されました

システム チェック

Give me an overview of the current database.

database_overview

アクティブな接続

What queries are currently running on the database?

list_active_queries

インストール済みの拡張機能

What extensions are installed in this database?

list_installed_extensions

利用可能な拡張機能

What extensions are available that I can install?

list_available_extensions

2. スキーマとカタログの探索

テスト目標

自然言語プロンプト

ツールが呼び出されました

テーブルを一覧表示する

Show me all the tables in the current database.

list_tables

インデックスを検査する

List all indexes in the database and which tables they belong to.

list_indexes

ビューを探索する

What views are available in the public schema?

list_views

テーブル トリガーを確認する

Show me the triggers defined on the orders table.

list_triggers

3. データのクエリとフィルタ（execute_sql）

テスト目標

自然言語プロンプト

ツールが呼び出されました

集計クエリ

Show me the 3 most expensive products in the 'Laptops' category.

execute_sql

結合クエリ

Find all customers who have placed an order in the last 6 months.

execute_sql

一致しないレコード

Which customers haven't placed any orders yet?

execute_sql

4. クエリのパフォーマンスと説明プラン（get_query_plan）

テスト目標

自然言語プロンプト

ツールが呼び出されました

説明プラン

Explain the query plan for a query that finds all customers who have not placed an order in the last 6 months.

get_query_plan

インデックスの検証

Get the query plan for SELECT * FROM products WHERE category = 'Audio' and tell me if it uses the index.

get_query_plan

5. データベースのメンテナンスと診断

テスト目標

自然言語プロンプト

ツールが呼び出されました

テーブルの肥大化

List the top five most bloated tables.

list_top_bloated_tables

ロックの競合

Show me if there are any active locks or blocked transactions.

list_locks

自動バキュームの設定

Show me the current autovacuum configuration.

list_autovacuum_configurations

無効なインデックス

Check for any invalid indexes in the database.

list_invalid_indexes

7. クリーンアップ

Codelab が完了したら、起動したローカル コンテナとプロセスをクリーンアップします。

  1. Antigravity CLI を終了するには、/quit と入力します（または Ctrl+D を 2 回押します）。
  2. MCP ツールボックス サーバーを実行しているターミナルタブに切り替え、Ctrl+C を押して停止します。
  3. AlloyDB Omni Docker コンテナを停止して削除します。
    docker stop alloydbomni
docker rm alloydbomni

8. 完了

これでこの Codelab は終了です。コンテナに AlloyDB Omni をデプロイし、事前構築済みの AlloyDB Omni ツールセットを使用してデータベース向け MCP ツールボックスを構成し、Antigravity CLI と統合して、自然言語を使用してデータベースのクエリと管理を行いました。

学習した内容

  • Docker を使用して AlloyDB Omni コンテナをデプロイして検証する方法。
  • Agentic Workflows をテストするためにサンプル テーブルとインデックスにデータを入力する方法。
  • 事前構築済みの alloydb-omni ツール構成を使用して、データベース向け MCP ツールボックスを構成して実行する方法。
  • Antigravity CLI を MCP ツールボックスに接続し、スキーマ検出、SQL クエリ、クエリプラン分析、データベース診断のための自然言語プロンプトを実行する方法。

詳しくは、次のリソースをご覧ください。

9. アンケート

このチュートリアルの利用方法をお選びください。

全体を通して読むだけ 内容を読んで演習をやり遂げる