【調査レポ11】Google Antigravity SDK × MCP連携！Model Context Protocolで外部ツールをプラグイン拡張する

Antigravity SDK入門 AI

前回の調査レポ10では、Google Antigravity SDKの公式パラメータ subagents を活用し、リーダーと専門サブエージェント（リサーチャー・アナリスト）によるAIチーム編成の協調ワークフローを検証しました。

今回は、調査レポ5の設定パラメータ一覧でも登場していた注目の機能「mcp_servers（MCP連携）」を取り上げます！オープン標準規格である「MCP（Model Context Protocol）」サーバーと Google Antigravity SDK を接続し、外部ツールをプラグイン感覚でAIエージェントへ追加する手法について調べた内容をお届けします。

これまでの連載では、エージェント内で自作したPython関数を tools=[func] として直接渡す手法を扱ってきました。しかし、実務やシステム開発では「すでに他で開発されたツール資産を活用したい」「別のプログラミング言語で動いているマイクロサービスと連携させたい」という場面が多くあります。Google Antigravity SDKの mcp_servers パラメータを活用することで、エージェント本体に直接ツールを書き込むことなく、独立したMCPサーバーから安全かつ柔軟にツール機能を取り込むことが可能になります！

なぜ今「MCP（Model Context Protocol）」なのか？

MCP（Model Context Protocol）とは、AIモデル（クライアント）と、ツールやデータソース（サーバー）の間の通信を標準化するために策定されたオープンプロトコルです。

従来のエージェント開発とMCPによるアーキテクチャの違いには、以下のような特徴があります。

  • ツールの高度な疎結合化（モジュール化）
    ツール関数をエージェントのコード内に直接埋め込む必要がなく、外部プロセス（MCPサーバー）として独立して動作させることができます。
  • ツールの共通資産化と再利用性
    一度作成したMCPサーバーは、Google Antigravity SDKだけでなく、MCP規格に対応した他のAIクライアントや開発ツールからもそのまま共通で呼び出して使い回すことができます。
  • 言語や環境の壁を越えた連携
    標準規格（JSON-RPC）に則って通信するため、Pythonで書かれたエージェントからNode.jsやGo言語、Rustなどで構築されたMCPサーバーのツールをシームレスに利用できます。

Antigravity SDKのMCP接続機能：McpStdioServerとmcp_serversオプションの仕組み

本記事の主眼は、Google Antigravity SDKを「MCPクライアント」として活用し、独立して稼働する外部のMCPサーバーに接続して、AIエージェントに多彩なツール機能を自律実行させることです。
Antigravity SDKでは、ローカルプロセスとして動作するMCPサーバーと通信するために types.McpStdioServer を使用し、エージェント設定である LocalAgentConfig の mcp_servers オプションに登録します。

types.McpStdioServer の基本構文と主要引数

標準入出力（stdio）を介してMCPサーバーと通信する場合、以下のように types.McpStdioServer インスタンスを生成します。

from google.antigravity import types

system_mcp = types.McpStdioServer(
    name="system_metrics_server",  # サーバーの一意な識別名
    command=sys.executable,        # サーバーを起動する実行ファイル（Python仮想環境）
    args=[server_script],          # 起動時に渡す引数リスト
    env={"DEBUG": "0"}             # （省略可）子プロセスに渡す環境変数辞書
)
引数名型解説と役割
namestrMCPサーバーの一意な識別名です。英数字やアンダースコア等で指定し、エージェント内部でのサーバー管理やログ識別に利用されます。
commandstrターミナル上でMCPサーバーを起動するときに入力する「先頭の実行コマンド（またはスクリプトを動かすインタープリタのパス）」を指定します。
・Pythonスクリプトを実行する場合：そのスクリプトを動かすPythonインタープリタ（仮想環境を維持できる sys.executable を推奨）
・Node.js製サーバーの場合：パッケージ実行コマンド（"npx" や "node" など）
・コンパイル済みバイナリの場合：実行可能バイナリ自体のファイルパス（"/path/to/server" など）
argslist[str]コマンドに渡す引数のリストです。スクリプトファイルのパス（絶対パスを推奨）や、CLIフラグ・起動オプションをリスト形式（["引数1", "引数2"]）で指定します。
envdict[str, str]（省略可）MCPサーバープロセスに引き渡す環境変数の辞書です。APIキーや設定値を子プロセスに個別で渡したい場合に活用できます。

【ターミナルでの実行コマンドと McpStdioServer の対応関係】
普段ターミナルで手動実行するコマンドラインと、command / args の設定は以下のようにそのまま1対1で対応しています。MCPサーバーがどのプログラミング言語で作られているかによって、適切な起動コマンドやインタープリタを command に指定します。

ターミナルで手動実行する場合の例command（実行コマンド・インタープリタ）args（引数リスト）
python3 system_mcp_server.pysys.executable（または "python3"）["system_mcp_server.py"]
※サンプルのPythonコードでは絶対パスを格納した変数 [server_script] を渡しています
npx -y @modelcontextprotocol/server-filesystem /path"npx"["-y", "@modelcontextprotocol/server-filesystem", "/path"]
uvx mcp-server-fetch"uvx"["mcp-server-fetch"]
docker run -i --rm my-mcp-server"docker"["run", "-i", "--rm", "my-mcp-server"]

なぜ command=sys.executable を指定するのか？

Pythonで作成したMCPサーバースクリプトを実行する場合、command="python" や command="python3" と記述したくなるかもしれません。
しかし、実務や開発環境で仮想環境（.venv や uv、poetry 等）を利用している場合、文字列で "python3" を指定すると、OSのグローバルなPython環境が優先的に呼び出されてしまうケースがあります。その結果、仮想環境内にインストールしたはずのパッケージ（mcp や依存ライブラリ）が見つからず、ModuleNotFoundError でサーバー起動に失敗するという問題が発生します。

そこで、sys.executable を指定することが推奨されます。sys.executable には「現在エージェントを実行しているPythonインタープリタそのものの絶対パス」が格納されているため、エージェントと同じ仮想環境のPythonが確実に使われ、インストール済みのライブラリをスムーズに読み込んでサーバープロセスを立ち上げることが可能になります。

mcp_servers オプションの特徴

LocalAgentConfig に用意されている mcp_servers オプションには、通常のエージェント開発を大幅に効率化する以下のような特徴があります。

  • 複数サーバーの同時接続（リスト指定）
    mcp_servers=[server_a, server_b, ...] のように、リスト形式で複数の独立したMCPサーバーを同時に登録できます。例えば「システム管理MCPサーバー」と「Web検索MCPサーバー」を並行して接続し、1人のエージェントに多彩な専門ツール群をまとめ役として持たせることが可能です。
  • 動的なツール自動検出（Tool Discovery）
    従来のエージェント設定（tools=[func]）では、利用したいPython関数をエージェントコード内で事前にインポートし、引数や戻り値の型アノテーションを記述する必要がありました。一方、mcp_servers を使用すると、エージェント起動時にSDKがMCPサーバーからツール仕様（tools/list）をJSON-RPC経由で自動取得・登録してくれます。エージェント側のコードにツールの具体的な実装を書く必要がありません。
  • 通常の tools オプションとの併用が可能
    手元で手軽に動かしたいPython関数（tools）と、外部プロセスとして分離されたMCPツール群（mcp_servers）は、同一のエージェント設定内で共存させることが可能です。用途に応じた柔軟なハイブリッド構成が実現できます。
  • 安全なプロセスのライフサイクル管理
    async with Agent(config) as agent: のコンテキストマネージャ構文により、エージェントの処理開始時に子プロセスが自動起動され、処理終了時には例外発生の有無にかかわらずプロセスが安全にクリーンアップされます。終了漏れによるゾンビプロセスの残存を防ぎやすい設計となっています。

実践ステップ1：テスト用MCPサーバーの作成（system_mcp_server.py）

今回は、Node.jsなどの追加環境を導入することなく、Python環境だけで手軽に接続検証ができるよう、公式の FastMCP ライブラリを用いて最小限のシステム情報MCPサーバー（system_mcp_server.py）を用意しました。
※なお、本格的な自作MCPサーバーの詳細な構築手順については、次回以降の調査レポで深く掘り下げる予定です！

import shutil
import platform
import os
from mcp.server.fastmcp import FastMCP

# テスト用MCPサーバーの初期化
mcp = FastMCP("SystemMetricsServer")

@mcp.tool()
def get_disk_usage(path: str = "/") -> str:
    """指定されたパスのディスク使用量（全体・使用量・空き容量）を取得するツール。

    Args:
        path (str): 調査対象のパス (デフォルトはルート '/')

    Returns:
        str: ディスク使用状況テキスト
    """
    try:
        total, used, free = shutil.disk_usage(path)
        return (
            f"パス '{path}' のディスク情報:\n"
            f"- 全体容量: {total // (1024**3)} GB\n"
            f"- 使用中: {used // (1024**3)} GB\n"
            f"- 空き容量: {free // (1024**3)} GB"
        )
    except Exception as e:
        return f"ディスク情報取得エラー: {e}"

@mcp.tool()
def get_system_summary() -> str:
    """ホスト環境のOS種別、マシンアーキテクチャ、CPU論理コア数を取得するツール。

    Returns:
        str: システム基本情報サマリー
    """
    return (
        f"ホストシステムサマリー:\n"
        f"- OS: {platform.system()} {platform.release()}\n"
        f"- マシンアーキテクチャ: {platform.machine()}\n"
        f"- CPU論理コア数: {os.cpu_count()} コア"
    )

if __name__ == "__main__":
    # stdio トランスポート（標準入出力）でサーバーを待機起動
    mcp.run()

【インポートしているPython標準モジュールの解説】
上記のサーバーコードでは、以下の標準ライブラリを活用してシステム情報を取得しています。

  • shutil：ファイルやディレクトリの高水準な操作（移動やコピーなど）を提供する標準ライブラリです。ここでは shutil.disk_usage(path) を使用し、指定パスの総容量・使用量・空き容量を簡潔に取得しています。
  • platform：実行しているOSの種類やカーネル、ハードウェア構成を調査するための標準ライブラリです。platform.system()（OS名）、platform.release()（OSバージョン）、platform.machine()（CPUアーキテクチャ）などの環境情報を取得しています。
  • os：オペレーティングシステム依存の機能や環境変数、ファイルパスを扱う基本ライブラリです。ここでは os.cpu_count() を使ってCPUの論理コア数を取得しています（※ステップ2のクライアント側でも、実行スクリプトの絶対パスを解決する os.path.abspath() として活用しています）。

実践ステップ2：MCPサーバーに接続するエージェントコード（mcp_agent_demo.py）

Google Antigravity SDK を使い、上記で作成したMCPサーバーへ接続してツールを自律実行させるエージェントプログラム（mcp_agent_demo.py）です。

import os
import sys
import asyncio

# 1. 安全対策：python-dotenv ライブラリの検出と環境変数の読み込み
try:
    from dotenv import load_dotenv
    load_dotenv()
except ImportError:
    print("注意: python-dotenv がインストールされていません。環境変数から直接APIキーを読み込みます。")

# 2. Google Antigravity SDK のインポート
try:
    from google.antigravity import Agent, LocalAgentConfig, types
except ImportError:
    print("エラー: google.antigravity パッケージが見つかりません。pip install google-antigravity で導入してください。", file=sys.stderr)
    sys.exit(1)

async def main():
    api_key = os.environ.get("GEMINI_API_KEY")
    if not api_key:
        print("エラー: GEMINI_API_KEY が設定されていません。.env ファイルを確認してください。", file=sys.stderr)
        return

    print("=== Google Antigravity SDK × MCP (Model Context Protocol) 連携デモを開始します ===\n")

    # 3. 接続先MCPサーバーの指定（types.McpStdioServer）
    # 自作の system_mcp_server.py を現在のPythonインタープリタで起動する設定
    server_script = os.path.abspath("system_mcp_server.py")
    if not os.path.exists(server_script):
        print(f"エラー: MCPサーバースクリプト '{server_script}' が見つかりません。", file=sys.stderr)
        return

    system_mcp = types.McpStdioServer(
        name="system_metrics_server",
        command=sys.executable,  # 実行中の仮想環境の Python を使用
        args=[server_script]
    )

    # 4. エージェント設計（mcp_servers パラメータに登録）
    # ※ tools パラメータに関数を渡さなくても、MCPサーバー経由でツールが自動検出されます
    config = LocalAgentConfig(
        system_instructions=(
            "あなたはシステム管理を支援するテクニカルサポートエージェントです。"
            "接続されているMCPサーバー（system_metrics_server）から提供されるツールを適宜呼び出して、"
            "正確なシステム情報やディスク空き容量を調査し、わかりやすく報告してください。"
        ),
        mcp_servers=[system_mcp],
        model="gemini-3.1-flash-lite"
    )

    # 5. エージェントの起動とMCPツールの自律実行
    user_request = "現在のホストシステムの構成情報と、ルートディレクトリ ('/') のディスク空き容量を調べて教えてください。"
    print(f"【ユーザーからの依頼】: {user_request}\n")
    print("▶ エージェントがMCPサーバーと接続し、自律的にツールを呼び出して調査を開始します...\n")

    async with Agent(config) as agent:
        response = await agent.chat(user_request)
        final_answer = await response.text()

        print("==================================================")
        print(" 🏆 [MCPサーバー連携エージェントによる調査結果]")
        print("==================================================")
        print(f"{final_answer}\n")

    print("=== MCPサーバー連携タスクが正常に完了しました ===")

if __name__ == "__main__":
    asyncio.run(main())

プログラムコードの詳細解説：MCPサーバー接続と自律実行の流れ

Antigravity SDKをMCPクライアントとして使用するにあたり、押さえておきたい実装の重要ポイントと内部の動作シーケンスです。

1. スクリプトの絶対パス解決と事前存在確認

server_script = os.path.abspath("system_mcp_server.py") により、MCPサーバースクリプトの絶対パスを取得し、os.path.exists(server_script) でファイルの実在を事前にチェックしています。
プログラムの実行ディレクトリ（CWD）が異なる場所であっても、パスのズレによる実行失敗を防ぐための記述パターンです。

2. types.McpStdioServer による接続定義

    system_mcp = types.McpStdioServer(
        name="system_metrics_server",
        command=sys.executable,  # 実行中の仮想環境の Python を使用
        args=[server_script]
    )

前述の通り、command=sys.executable を指定することで、エージェントを実行している現在のPython仮想環境（.venv）のインタープリタが確実に使用されます。これにより、仮想環境にインストールした FastMCP などの依存パッケージが見つからないトラブルを未然に回避できます。

3. LocalAgentConfig への登録とシステムプロンプトの設計

LocalAgentConfig には通常の tools=[...] を一切渡していません。それでも、mcp_servers=[system_mcp] を指定するだけで、SDKがMCPサーバーからツール定義を自律的に取得してエージェントに登録してくれます。
さらに、system_instructions の中で「接続されているMCPサーバー（system_metrics_server）から提供されるツールを適宜呼び出して調査する」方針を自然言語で伝えておくことで、モデルが適切なタイミングでツールを選択・実行する精度が高まります。

4. エージェント内部での協調動作シーケンス（裏側の動き）

エージェントが実行された際、SDKの裏側では以下のような一連の通信が自動で行われています。

  • ① サーバー起動とハンドシェイク：async with Agent(config) に入ると、SDKがサブプロセスとしてサーバーを起動し、標準入出力（stdio）経由で初期化ハンドシェイク（initialize）を行います。
  • ② ツール仕様の自動取得（Dynamic Discovery）：SDKがMCPサーバーへ tools/list リクエストを送信し、提供されている関数名・引数型・説明文（Docstring）を自動取得してGeminiモデルのコンテキストに登録します。
  • ③ ツールの自律選択と呼び出し（Tool Calling）：ユーザーからの依頼を理解したモデルが必要なツール呼び出しを決定し、SDKがMCPサーバーへ tools/call リクエストを発行して実行結果を受け取ります。
  • ④ 回答生成と安全なクリーンアップ：ツールの実行結果をもとにエージェントが最終的な回答をまとめます。async with ブロックを抜けると、SDKが子プロセスを安全にシャットダウンします。

5. 応用展開：複数のMCPサーバーを同時に接続する構成

mcp_servers はリスト形式であるため、自作のPythonサーバーだけでなく、オープンソースで公開されているMCPサーバー（例：Webページ取得用の mcp-server-fetch など）を同時に登録して1人のエージェントに束ねることも容易です。

# 複数MCPサーバーの同時接続イメージ
config = LocalAgentConfig(
    system_instructions="あなたはシステム監視とWeb調査を担うアシスタントです。",
    mcp_servers=[
        system_mcp,  # 自作のシステム管理MCPサーバー（Python）
        types.McpStdioServer(
            name="fetch_server",
            command="uvx",
            args=["mcp-server-fetch"]  # 外部公開されているWeb取得MCPサーバー
        )
    ],
    model="gemini-3.1-flash-lite"
)

このように設定するだけで、エージェントは内部のシステム情報だけでなく、外部Webサイトの情報取得ツールもシームレスに使いこなせるようになります。

プログラムの実行手順と動作確認

手元の環境でMCP連携プログラムを動かす手順です。
環境構築の手順については過去の環境構築編をご参照ください。

手順1. パッケージ準備とAPIキー設定

# 仮想環境の有効化
source .venv/bin/activate

# パッケージのインストール（mcp パッケージを追加）
pip install google-antigravity python-dotenv mcp

# APIキーの設定 (.env ファイルを作成)
echo 'GEMINI_API_KEY="YOUR_GEMINI_API_KEY_HERE"' > .env

手順2. スクリプトの実行

python3 mcp_agent_demo.py

手順3. 実行ログと調査結果の確認

=== Google Antigravity SDK × MCP (Model Context Protocol) 連携デモを開始します ===

【ユーザーからの依頼】: 現在のホストシステムの構成情報と、ルートディレクトリ ('/') のディスク空き容量を調べて教えてください。

▶ エージェントがMCPサーバーと接続し、自律的にツールを呼び出して調査を開始します...

==================================================
 🏆 [MCPサーバー連携エージェントによる調査結果]
==================================================
現在のホストシステムの構成情報およびルートディレクトリ (`/`) のディスク利用状況について報告いたします。

### システム構成情報
*   OS: macOS / Linux (検証環境)
*   アーキテクチャ: arm64 / x86_64
*   CPU: 8コア

### ディスク空き容量 (`/` ルートディレクトリ)
*   全体容量: 500 GB
*   使用量: 150 GB
*   空き容量: 350 GB

ご確認のほどお願いいたします。

=== MCPサーバー連携タスクが正常に完了しました ===

エージェント自身にはツールのPythonコードが一切書かれていないにもかかわらず、外部のMCPサーバーを自動的に呼び出し、実データ（OSやディスク容量）を取得して自然な日本語で回答している様子が確認できます！

開発上の注意点

Google Antigravity SDKでMCPサーバーと連携する際、気をつけておきたい「2つの注意点」をまとめました。

① stdio通信における標準出力（print文）の混入防止

types.McpStdioServer では、エージェントとサーバーが「標準入出力（stdin / stdout）」を介してJSON-RPCフォーマットでメッセージをやり取りしています。
そのため、もしMCPサーバー側のコード内にデバッグ目的で print("debug message") などの通常の標準出力を書いてしまうと、JSON-RPCのデータ列に余計な文字列が混入してパースエラーとなり、通信が切断されてしまう落とし穴があります。デバッグログを出力したい場合は、標準エラー出力（sys.stderr.write(...)）やロギングライブラリ（logging）を利用することを推奨します。

② 外部依存コマンドやパスの指定ミス防止

オープンソースのMCPサーバーを利用する場合、コマンドとして npx や uvx を指定することが一般的です。しかし、実行環境によってはそれらのコマンドへのパスが通っていなかったり、Node.jsのバージョンが合わずにサーバー起動に失敗するリスクがあります。まずはローカル環境のターミナルで対象のコマンドが直接実行できるかテストしてから、McpStdioServer に設定することを推奨します。

まとめと次回予告

今回は、Google Antigravity SDKの「mcp_servers」設定パラメータを活用し、オープン標準規格「MCP（Model Context Protocol）」サーバーと接続して、外部ツールをプラグイン感覚で即座にAIエージェントに組み込む手法を検証しました。

MCPを活用することで、ツールとエージェント本体が分離され、一度作ったツールを様々なAI環境で再利用できるようになります。

今回はテスト用の軽量MCPサーバーを接続先として使用しましたが、次回以降の調査レポでは「Pythonによる実用的な自作MCPサーバーの本格構築と機能拡張」に焦点を当て、さらに一歩進んだ開発手順をお届けする予定です。ぜひご期待ください！

コメント

タイトルとURLをコピーしました