mcp-toolbox を採用する前に読む: prebuilt ツールと tools.yaml の境界

エージェントにデータベースを渡すときの接続コード問題

LLM エージェントから PostgreSQL や BigQuery を触らせようとすると、たいてい同じ作業が発生する。コネクションプールを用意し、認証情報を読み込み、スキーマを列挙する関数を書き、SQL を実行する関数を書き、それらをツール定義としてエージェント側のフレームワークに登録する。データベースの種類が増えるたびに、この一式がドライバごとに複製されていく。

mcp-toolbox はこの層を独立したサーバープロセスとして切り出す。README の説明では、AI エージェント、IDE、アプリケーションをデータベースに直接つなぐ MCP サーバーであり、用途は二つに分かれるとされている。一つはビルド時に使う既製の MCP サーバー、もう一つは実行時に使うカスタムツールのフレームワークである。対象読者は、IDE から手元のデータベースを覗きたい開発者と、本番エージェントに安全なツールだけを渡したいチームの両方になる。

prebuilt モードが生む「設定ファイル 5 行」の体験

README が最初に示すのは prebuilt ツールの使い方である。クライアントの MCP 設定ファイル、通常は mcp.json か claude_desktop_config.json に、次のようなブロックを追加する。

{"mcpServers": {"toolbox-postgres": {"command": "npx", "args": ["-y", "@toolbox-sdk/server", "--prebuilt=postgres", "--stdio"]}}}

--prebuilt=<database> を付けて起動すると、そのデータベースを操作する標準ツール一式が有効になる。README は list_tables と execute_sql を例として挙げている。--prebuilt=postgres/data のようにスラッシュでツールセットを指定すれば、SQL 系のツールだけに絞ることもできる。接続に必要な環境変数は Prebuilt Tools Reference にまとまっており、README の本文には列挙されていない。

ここで効いているのは、接続文字列の管理とツール定義がサーバー側に寄る点だ。MCP クライアント側にはデータベースドライバもスキーマ知識も要らない。対応データベースは Google Cloud 系の AlloyDB、BigQuery、Cloud SQL、Spanner、Firestore、Knowledge Catalog に加え、PostgreSQL、MySQL、MariaDB、SQL Server、Oracle、MongoDB、Redis、Elasticsearch、CockroachDB、ClickHouse、Couchbase、Neo4j、Snowflake、Trino が挙がっている。ただし README の一覧は「and more」で終わっており、ここに載っていないものが使えないとは限らないし、載っているものが全ツールを提供するとも限らない。実際のツール単位の対応は Prebuilt Tools Reference を見る必要がある。

tools.yaml による source と tool の分離

prebuilt モードは探索向けであり、本番向けではない。README が二つ目の用途として挙げるカスタムツールのフレームワークでは、あらかじめ決めたロジックを持つツールを自分で定義する。安全性の根拠として README が示すのは Restricted Access、Structured Queries、Semantic Search の三つである。

重要なのは、この構成ではエージェントが任意の SQL を組み立てるのではなく、定義済みのクエリをパラメータ付きで呼び出す形になる点だ。エージェントに渡るのは「このツールはこの入力を取り、このクエリを実行する」という契約であって、SQL 文字列そのものではない。読み取り専用のクエリだけを並べれば、書き込み系の操作は原理的にツール一覧に現れない。

ただし README の抜粋はカスタムツールの節の冒頭で切れており、tools.yaml の具体的なキー、source の書き方、tool の種別は確認できない。この記事では推測で補わない。採用を検討するなら mcp-toolbox.dev の該当ページを直接読むべき箇所である。

サーバーの起動方法と SDK 経由の組み込み

サーバー自体の導入は README では Install & Run the Toolbox server の節に分離されている。実行方法として Docker とバイナリが挙げられており、prebuilt の例では npx 経由で @toolbox-sdk/server を起動している。つまり Node のパッケージとして配布される経路と、Go 製のバイナリを直接動かす経路、コンテナで動かす経路が併存する。

エージェントフレームワークへの組み込みは MCP 経由だけではない。README は ADK、LangChain、LlamaIndex、あるいは自作エージェントに 10 行未満で統合できると述べており、SDK が Python、JS/TS、Go、Java の 4 言語で用意されている。バッジが示すパッケージ名は toolbox-core、@toolbox-sdk/core、github.com/googleapis/mcp-toolbox-sdk-go、com.google.cloud.mcp/mcp-toolbox-sdk-java である。MCP プロトコルを話さないアプリケーションでも、SDK を介して同じツール定義を呼び出せるという整理になる。

サーバー側が受け持つのは接続プーリング、IAM を含む認証、OpenTelemetry によるメトリクスとトレーシングである。これらを各エージェント実装に書き直さずに済む点が、単なる SQL プロキシとの違いになる。

リポジトリ名の変更が示す来歴と、それが実務に与える影響

README には重要として、リポジトリ名が genai-toolbox から mcp-toolbox に変わったことが書かれている。git remote set-url origin https://github.com/googleapis/mcp-toolbox.git で追従できる。元の名称は Gen AI Toolbox for Databases で、開発が MCP の策定より先行していたため、のちに MCP 互換に合わせて改名したという経緯が注記されている。

この来歴は実務では二つの形で現れる。一つは、古い記事やスクリプトが genai-toolbox の URL やモジュール名を参照している可能性である。もう一つは、ドキュメント内に genai 由来の用語が残っている箇所があることだ。検索でヒットした情報の鮮度を判断する材料になる。

バージョニングについては README に Versioning の節が置かれているが、抜粋には方針が含まれていない。リリース番号は v1.10.0、v1.9.0、v1.8.0 と 1.x 系が続いており、後方互換を前提とした運用に見えるが、これは番号からの推測であって README の記述ではない。

prebuilt モードを本番に置くべきでない理由

最も見落とされやすい制約は、prebuilt モードの位置づけそのものである。README はこれを Build-Time と明記し、用途をデータ探索、スキーマ確認、コード生成としている。execute_sql のような汎用ツールが有効になる以上、エージェントは与えられた権限の範囲で任意のクエリを発行できる。読み取り専用ユーザーを割り当てる、対象データベースを分けるといった制御はサーバーではなくデータベース側の権限設計に依存する。

もう一つの限界は、README の対応データベース一覧が網羅的でないことだ。and more と書かれている以上、この一覧を「対応していないデータベースのリスト」として読むのは誤りである。逆に、一覧に名前があってもツールセットの中身までは保証されない。--prebuilt=<database>/<toolset> の toolset 名もデータベースごとに異なる。

三つ目は、managed な選択肢の存在である。README は Google Cloud MCP Servers を、prebuilt ツール付きのマネージドな MCP 体験として紹介し、差分は FAQ へのリンクで説明している。セルフホストの mcp-toolbox とマネージド版のどちらを選ぶかは、この FAQ を読まないと判断できない。README 本文だけでは比較材料が足りない。

Postgres MCP サーバーとの設計の違い

同じ「LLM から PostgreSQL を触る」目的では、単一データベース向けの MCP サーバー実装が複数存在する。典型的なものは PostgreSQL 専用で、接続文字列を環境変数か引数で受け取り、スキーマ参照とクエリ実行のツールを公開する。

mcp-toolbox との差は対応範囲の広さだけではない。単一データベース向けの実装は、そのデータベースの機能をそのまま露出させる方向に設計される。一方 mcp-toolbox のカスタムツールは、公開する操作をあらかじめ定義したものに限定する方向に設計される。エージェントに何を許すかという問いへの答え方が逆である。

もう一つの差は、複数データベースをまたぐ構成を取れるかどうかである。mcp-toolbox は prebuilt の一覧が示すとおり多数のデータベースを対象にしており、SDK も 4 言語ぶん用意されている。単一データベース向けの実装は、その 1 種類で十分な場合に設定が少なくて済む。どちらが優れているかではなく、公開したい操作の粒度で選ぶべきものである。

ライセンスと更新コストの見積もり

ライセンスは Apache-2.0 である。特許条項と変更点の明示義務を含む寛容なライセンスで、商用製品への組み込みや改変配布を妨げるものではない。ただし本記事は法的助言ではない。自社の配布形態における NOTICE の扱いなどは、法務に確認する項目である。

更新コストは 1.x 系が続いている点と、リポジトリ名の変更という前例から見積もれる。名前の変更は URL とモジュールパスに影響するが、README が示すのは git remote の更新手順だけであり、依存側のパッケージ名が変わったかどうかは読み取れない。SDK のバージョンは言語ごとに別管理されているため、サーバー本体の v1.10.0 と SDK のバージョンは連動しない。アップグレード時は両方を別々に確認する必要がある。

prebuilt ツールの toolset 名や環境変数は、データベースごとのリファレンスに依存している。ここが変わると MCP 設定ファイルの修正が必要になる。設定をリポジトリで管理し、差分をレビューできるようにしておくのが現実的な運用になる。

編集部の結論

スキーマ探索やクエリの下書きを IDE から行いたい個人開発者、そして本番エージェントに読み取り専用の構造化クエリだけを渡したいチームには向く。逆に、任意の SQL をエージェントに書かせたい場合や、MCP を経由せずアプリから直接データベースを叩く既存構成には不要な層になる。採用前に確認すべきは、対象データベースが prebuilt ツール一覧に載っているか、そして tools.yaml の source と tool の分離で権限をどこまで絞れるかである。Apache-2.0 なので自社製品への組み込み自体は妨げられないが、Google Cloud のマネージド MCP サーバーとの差分は README が FAQ へのリンクを示すだけで本文では説明していない。

公式情報源

1. googleapis/mcp-toolbox on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases