Model Context Protocol (MCP) Agent Frameworks Demo

Model Context Protocol（MCP）エージェントフレームワークのデモとベンチマークプラットフォーム

このリポジトリでは、Model Context Protocol（MCP）サーバーのツールを使用する LLM エージェントを、以下の複数のフレームワークで紹介します。

• Google Agent Development Kit（ADK）
• LangGraph エージェント
• OpenAI エージェント
• Pydantic-AI エージェント

リポジトリの構成

• 単一の MCP サーバーを使用するエージェント - 学習用の例と基本的なパターン
• 複数の MCP サーバーを使用するエージェント - MCP サーバー間の連携を含む高度な使い方
• 評価スイート - 包括的なベンチマークツール
  • 評価ダッシュボード：モデルを比較できるインタラクティブな Streamlit UI
  • マルチモデルベンチマーク：複数の LLM を対象とした並列／逐次評価
  • 豊富なメトリクス：使用状況の分析、コストの比較、パフォーマンスランキング

このリポジトリには、以下の Python MCP サーバーも含まれています。

• example_server.py は、MCP Python SDK クイックスタートをベースに、日時ツールを追加し、エージェントから呼び出されるサーバーとして動作するよう変更されています
• mermaid_validator.py - mermaid-cli を使用した Mermaid 図の検証サーバー

トレースには Pydantic Logfire を使用します。

クイックスタート

1. cp .env.example .env

• GEMINI_API_KEY および／または OPENAI_API_KEY を追加します
  • 各スクリプトは、対象のフレームワークがサポートする任意のプロバイダーのモデルを使用するように調整できます
• [任意] Logfire の Web UI で評価を可視化する場合は、LOGFIRE_TOKEN を追加します

2. エージェントフレームワークのスクリプトをテストします。例：

• uv run agents_mcp_usage/basic_mcp/basic_mcp_use/pydantic_mcp.py

  • デフォルトでは GEMINI_API_KEY が必要です

• uv run agents_mcp_usage/basic_mcp/basic_mcp_use/oai-agent_mcp.py

  • デフォルトでは OPENAI_API_KEY が必要です

3. Docker 化された単一モデルのベンチマークを実行します（依存関係を分離）

• make benchmark MODEL="openai:gpt-5.2 (none)" RUNS=5 PARALLEL=1

出力はコンソール、Logfire、または ADK Web UI で確認してください

プロジェクト概要

このプロジェクトでは、以下について学ぶことを目指しています。

1. 複数の LLM エージェントフレームワークで MCP を使用する方法
   • 単一の MCP サーバーを使用するエージェント（basic_mcp）
   • 複数の MCP サーバーを使用するエージェント（multi_mcp）
2. Logfire で LLM エージェントのトレースを確認する方法
3. PydanticAI evals で LLM を評価する方法

リポジトリ構成

• agents_mcp_usage/basic_mcp/ - 単一の MCP サーバーとの統合例

  • basic_mcp_use/ - 単一の MCP を使用する基本的な例を含みます：
    • adk_mcp.py - Google の Agent Development Kit（ADK 1.3.0）で MCP を使用する例
    • langgraph_mcp.py - LangGraph で MCP を使用する例
    • oai-agent_mcp.py - OpenAI Agents で MCP を使用する例
    • pydantic_mcp.py - Pydantic-AI で MCP を使用する例
    • pydantic_mcp_factory.py - 複数プロバイダーに対応するモデルファクトリーパターンの例

• agents_mcp_usage/multi_mcp/ - 複数の MCP サーバーとの高度な統合例

  • multi_mcp_use/ - 複数の MCP サーバーを同時に使用する例を含みます：
    • pydantic_mcp.py - Pydantic-AI Agent で複数の MCP サーバーを使用する例

• agents_mcp_usage/evaluations/ - ベンチマーク用の評価モジュール

  • mermaid_evals/ - Mermaid 図の修正タスク向けの包括的な評価スイート
    • evals_pydantic_mcp.py - 単一モデルテスト用のコア評価モジュール
    • run_multi_evals.py - 並列実行による複数モデルのベンチマーク
    • merbench_ui.py - 結果を可視化するインタラクティブなダッシュボード

• デモ用 Python MCP サーバー

  • mcp_servers/example_server.py - Python で実装された、ローカルで実行するシンプルな MCP サーバー
  • mcp_servers/mermaid_validator.py - Python で実装された、Mermaid 図検証用の MCP サーバー

基本的な MCP：単一サーバーの使用

basic_mcp ディレクトリでは、単一の MCP サーバーをさまざまなエージェントフレームワークに統合する方法を紹介します。各例は、次のような同様のパターンに沿っています：

1. 環境設定：環境変数の読み込みとロギングの設定
2. サーバーへの接続：ローカル MCP サーバーへの接続の確立
3. エージェントの設定：適切なモデルを使用するエージェントのセットアップ
4. 実行：クエリを指定してエージェントを実行し、応答を処理

これらの例の MCP サーバーでは、次の機能を提供します：

• 加算ツール（add(a, b)）
• 時刻ツール（get_current_time()）
• 動的な挨拶リソース（greeting://{name}）

基本的な MCP アーキテクチャ

graph LR
    User((User)) --> |"Run script<br>(e.g., pydantic_mcp.py)"| Agent

    subgraph "Agent Frameworks"
        Agent[Agent]
        ADK["Google ADK<br>(adk_mcp.py)"]
        LG["LangGraph<br>(langgraph_mcp.py)"]
        OAI["OpenAI Agents<br>(oai-agent_mcp.py)"]
        PYD["Pydantic-AI<br>(pydantic_mcp.py)"]
        
        Agent --> ADK
        Agent --> LG
        Agent --> OAI
        Agent --> PYD
    end

    subgraph "Python MCP Server"
        MCP["Model Context Protocol Server<br>(mcp_servers/example_server.py)"]
        Tools["Tools<br>- add(a, b)<br>- get_current_time()"]
        Resources["Resources<br>- greeting://{name}"]
        MCP --- Tools
        MCP --- Resources
    end

    subgraph "LLM Providers"
        OAI_LLM["OpenAI Models"]
        GEM["Google Gemini Models"]
        OTHER["Other LLM Providers..."]
    end
    
    Logfire[("Logfire<br>Tracing")]
    
    ADK --> MCP
    LG --> MCP
    OAI --> MCP
    PYD --> MCP
    
    MCP --> OAI_LLM
    MCP --> GEM
    MCP --> OTHER
    
    ADK --> Logfire
    LG --> Logfire
    OAI --> Logfire
    PYD --> Logfire
    
    LLM_Response[("Response")] --> User
    OAI_LLM --> LLM_Response
    GEM --> LLM_Response
    OTHER --> LLM_Response

基本的な MCP の例を試す：

# Google ADK example
uv run agents_mcp_usage/basic_mcp/basic_mcp_use/adk_mcp.py

# LangGraph example
uv run agents_mcp_usage/basic_mcp/basic_mcp_use/langgraph_mcp.py

# OpenAI Agents example
uv run agents_mcp_usage/basic_mcp/basic_mcp_use/oai-agent_mcp.py

# Pydantic-AI example
uv run agents_mcp_usage/basic_mcp/basic_mcp_use/pydantic_mcp.py

# Launch ADK web UI for visual interaction
make adk_basic_ui

基本的な MCP の実装について詳しくは、basic_mcp README をご覧ください。

複数の MCP：高度な使用方法

multi_mcp ディレクトリでは、複数の特化型 MCP サーバーに同時に接続し、連携させるための高度な手法を紹介します。この方法には、次のような利点があります：

1. ドメインの分離：各 MCP サーバーが特定のドメインや一連の機能に専念できます
2. モジュール性：システム全体に影響を与えずに、機能の追加、削除、更新ができます
3. スケーラビリティ：複数のサーバーに負荷を分散し、パフォーマンスを向上できます
4. 特化：各 MCP サーバーを特定のユースケースに合わせて最適化できます

複数の MCP のアーキテクチャ

graph LR
    User((User)) --> |"Run script<br>(e.g., pydantic_mcp.py)"| Agent

    subgraph "Agent Framework"
        Agent["Pydantic-AI Agent<br>(pydantic_mcp.py)"]
    end

    subgraph "MCP Servers"
        PythonMCP["Python MCP Server<br>(mcp_servers/example_server.py)"]
        MermaidMCP["Python Mermaid MCP Server<br>(mcp_servers/mermaid_validator.py)"]
        
        Tools["Tools<br>- add(a, b)<br>- get_current_time()"]
        Resources["Resources<br>- greeting://{name}"]
        MermaidValidator["Mermaid Diagram<br>Validation Tools"]
        
        PythonMCP --- Tools
        PythonMCP --- Resources
        MermaidMCP --- MermaidValidator
    end

    subgraph "LLM Providers"
        LLMs["PydanticAI LLM call"]
    end
    
    Logfire[("Logfire<br>Tracing")]
    
    Agent --> PythonMCP
    Agent --> MermaidMCP
    
    PythonMCP --> LLMs
    MermaidMCP --> LLMs
    
    Agent --> Logfire
    
    LLM_Response[("Response")] --> User
    LLMs --> LLM_Response

複数の MCP の例を試す：

# Run the Pydantic-AI multi-MCP example
uv run agents_mcp_usage/multi_mcp/multi_mcp_use/pydantic_mcp.py

# Run the multi-MCP evaluation
uv run agents_mcp_usage/evaluations/mermaid_evals/evals_pydantic_mcp.py

# Run multi-model benchmarking
uv run agents_mcp_usage/evaluations/mermaid_evals/run_multi_evals.py --models "gemini-2.5-pro-preview-06-05,gemini-2.0-flash" --runs 5 --parallel

# Dockerized benchmark for a single model (builds the image automatically)
make benchmark MODEL="openai:gpt-5.1 (none)" RUNS=5 PARALLEL=1

# Dockerized dry run (no API calls; useful for smoke tests)
make benchmark-dry-run MODEL="openai:gpt-5.1 (none)"

# Note: the Docker image installs benchmark-only dependencies.
# Run other demos/dashboards from your local environment.

# Launch the evaluation dashboard
uv run streamlit run agents_mcp_usage/evaluations/mermaid_evals/merbench_ui.py

複数の MCP の実装について詳しくは、multi_mcp README をご覧ください。

評価スイートとベンチマークダッシュボード

このリポジトリには、複数のフレームワークやモデルにわたって LLM エージェントのパフォーマンスをベンチマークするための包括的な評価システムが含まれています。この評価スイートでは、複数の MCP サーバーを使用し、Mermaid 図の修正タスクでエージェントをテストします。また、豊富なメトリクスと分析機能を提供します。

主な評価機能

• 複数レベルの難易度：包括的な評価に向けて、簡単、中程度、難しいテストケースを用意
• 複数モデルのベンチマーク：複数のLLMモデルを並列または順次に評価
• インタラクティブなダッシュボード：結果の可視化、コスト分析、モデル比較に対応したStreamlitベースのUI
• 多様なメトリクスの収集：トークン使用量、コスト分析、成功率、失敗の分類
• 堅牢なエラー処理：包括的な再試行ロジックと詳細な失敗分析
• エクスポート機能：後続の分析やレポート作成に使えるCSV形式の結果

ダッシュボードの機能

付属のStreamlitダッシュボード（merbench_ui.py）では、次の機能を利用できます。

• モデルランキング：精度、コスト効率、速度に基づくパフォーマンスのランキング
• コスト分析：詳細なコスト内訳と成功あたりのコスト指標
• 失敗分析：デバッグに役立つ分析情報を含む、分類済みの失敗理由
• パフォーマンスの推移：難易度レベルごとのモデルの動作を可視化
• リソース使用状況：トークン消費量とAPI呼び出しのパターン
• 比較分析：モデルのパフォーマンスを横並びで比較

評価をすぐに実行するコマンド

# Single model evaluation
uv run agents_mcp_usage/evaluations/mermaid_evals/evals_pydantic_mcp.py

# Dockerized single-model benchmark (isolated dependencies)
make benchmark MODEL="openai:gpt-5.1 (none)" RUNS=5 PARALLEL=1

# Multi-model parallel benchmarking
uv run agents_mcp_usage/evaluations/mermaid_evals/run_multi_evals.py \
  --models "gemini-2.5-pro-preview-06-05,gemini-2.0-flash,gemini-2.5-flash" \
  --runs 5 \
  --parallel \
  --output-dir ./results

# Launch interactive dashboard
uv run streamlit run agents_mcp_usage/evaluations/mermaid_evals/merbench_ui.py

この評価システムにより、LLMモデルやエージェントフレームワークを対象とした、堅牢で再現性の高いベンチマークを実行できます。研究や本番環境でのモデル選定の判断を支援します。

MCPとは？

Model Context Protocolは、アプリケーションが標準化された方法でLLMにコンテキストを提供できるようにし、コンテキストの提供と実際のLLMとのやり取りを分離します。

詳しくはこちら：https://modelcontextprotocol.io/introduction

MCPを使う理由

MCPは、リソース（データの公開）、プロンプト（再利用可能なテンプレート）、ツール（アクション）、サンプリング（補完）などのコンポーネントに明確な仕様を定めることで、開発プロセスを簡素化し、一貫性を促進します。

特に注目すべき利点は柔軟性です。MCPを使うと、ツールやデータの統合を全面的に見直さなくても、異なるLLMプロバイダー間でより簡単に切り替えられます。構造化されたアプローチを採用することで、モデルごとにカスタムツールを実装する際に生じがちな複雑さを軽減できる可能性があります。Google Agent Development Kit、LangGraph、OpenAI Agentsのようなフレームワークや、PydanticAIのようなライブラリはエージェントの構築を支援します。一方、MCPは、エージェントの推論（LLM）とその機能（ツールやデータ）との間のインターフェースの標準化に特化し、より相互運用性の高いエコシステムの実現を目指しています。

セットアップ手順

1. このリポジトリをクローンします

2. 必要なパッケージをインストールします。

   make install
   

   ADKのWeb UIを使用するには、次を実行します。

   make adk_basic_ui
   

3. .envファイルに環境変数を設定します。

   LOGFIRE_TOKEN=your_logfire_token
   GEMINI_API_KEY=your_gemini_api_key
   OPENAI_API_KEY=your_openai_api_key
   

4. 上記の例に従って、サンプルスクリプトを実行します

Logfireについて

Logfireは、Pydanticを開発したチームが提供する可観測性プラットフォームで、AIアプリケーションの監視を簡単にします。主な機能は次のとおりです。

• シンプルでありながら強力なダッシュボード
• Pythonオブジェクトを豊かに表示する機能など、Pythonを中心とした分析情報
• アプリケーションデータをSQLベースでクエリする機能
• 既存のツールを活用するためのOpenTelemetryサポート
• 検証結果の分析に対応したPydantic統合

Logfireを使うと、コードの実行状況を把握できます。モデルの動作を理解することが重要なLLMアプリケーションでは、特に役立ちます。