メインコンテンツへスキップ
Colab で開く Model Context Protocol (MCP) は、AI アプリケーションが大規模言語モデル (LLM) と情報をやり取りできるようにする標準化された通信プロトコルです。ハードウェアの互換性を大きく変えた汎用コネクタと同じように、MCP は LLM がさまざまなデータソースにアクセスし、外部ツールと連携するためのインターフェースを提供します。しかも、新しいサービスごとに個別のインテグレーションを作成する必要はありません。 Weave インテグレーションを使用すると、MCP クライアントと MCP サーバー間のアクティビティをトレースできます。これにより、MCP ベースのシステム全体にわたるツールの呼び出し、リソースへのアクセス、プロンプト生成を詳細に可視化できます。

仕組み

現在、このインテグレーションではクライアント側とサーバー側の操作をそれぞれ個別に取得しており、それらの相互作用をエンドツーエンドで可視化することはできません。エンドツーエンドの可観測性を実現するために、MCP に OpenTelemetry のトレースサポートを追加する提案が現在進められています。詳細は GitHub discussion #269 を参照してください。
Weave インテグレーションは、コア method に weave.op() デコレータを適用することで、Model Context Protocol (MCP) の主要なコンポーネントを自動的にトレースします。具体的には、mcp.server.fastmcp.FastMCP クラスと mcp.ClientSession クラスの method にパッチを適用します。 このインテグレーションにより、Weave は次の MCP コンポーネントをトレースします。 mcp_trace_timeline.png

インテグレーションを使用する

Weave インテグレーションは、MCP サーバーとクライアントの両方で使用できます。インストール後は、weave を import するための 1 行と初期化するための 1 行を追加するだけで、トレースを有効にできます。

前提条件

始める前に、必須のパッケージをインストールしてください。
pip install -qq "mcp[cli]" weave

設定

環境変数でMCPインテグレーションを設定します。
  • MCP_TRACE_LIST_OPERATIONS: サーバー側とクライアント側の両方でリスト操作 (list_toolslist_resourceslist_prompts) をトレースする場合は、true に設定します。

サーバー側インテグレーション

MCP サーバーをトレースするには、既存の FastMCP のセットアップに 2 行追加するだけです。1 行は Weave のインポート用、もう 1 行はクライアントの初期化用です。追加すると、ツール、リソース、プロンプト に関する操作が自動的にトレースされます。
# Weave をインポート(トレースに必須)
import weave
from mcp.server.fastmcp import FastMCP

# プロジェクト名で Weave を初期化する
weave_client = weave.init("my-project")

# MCP サーバーを設定する
mcp = FastMCP("Demo")

# ツールを定義する(この call はトレースされる)
@mcp.tool()
def add(a: int, b: int) -> int:
    """2つの数値を加算する。"""
    return a + b

# リソースを定義する(この call はトレースされる)
@mcp.resource("greeting://{name}")
def get_greeting(name: str) -> str:
    """パーソナライズされた挨拶を返す。"""
    return f"Hello, {name}!"

# プロンプトを定義する(この call はトレースされる)
@mcp.prompt()
def review_code(code: str) -> str:
    """コードレビュー用のプロンプトを返す。"""
    return f"Please review this code:\n\n{code}"

# サーバーを起動する
mcp.run(transport="stdio")

クライアント側のインテグレーション

クライアント側で必要な変更も 2 つだけです。Weave をインポートして初期化します。すべてのツール呼び出し、リソースへのアクセス、プロンプトのリクエストは自動的にトレースされます。
# Weave をインポート(トレースに必須)
import weave
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

# プロジェクト名で Weave を初期化する
weave_client = weave.init("my-project")

# MCP クライアントを設定して実行する
async with stdio_client(server_params) as (read, write):
    async with ClientSession(read, write) as session:
        # セッションを初期化する
        await session.initialize()
        
        # ツールを呼び出す(トレースされる)
        result = await session.call_tool("add", arguments={"a": 1, "b": 2})
        
        # リソースを読み取る(トレースされる)
        resource = await session.read_resource("greeting://user")
        
        # プロンプトを取得する(トレースされる)
        prompt = await session.get_prompt("review_code", arguments={"code": "print('Hello')"})

チュートリアル: mcp_demo の例

mcp_demo の例では、トレースのために Model Context Protocol (MCP) と Weave のインテグレーションを示します。クライアント側とサーバー側の両方のコンポーネントを計装し、それらのやり取りの詳細なトレースを取得する方法を紹介します。

例を実行する

  1. docsリポジトリをクローンし、mcp_demo の例にアクセスします:
    git clone https://github.com/wandb/docs
    cd docs/weave/examples/mcp_demo
    
    この例には、主に次の 2 つのファイルが含まれています:
    • example_server.py: FastMCP で構築されたデモ用の MCP サーバーです。ツール、リソース、プロンプト を定義します。
    • example_client.py: サーバーに接続し、そのコンポーネントとやり取りするクライアントです。
  2. 必須の依存関係を手動でインストールします:
    pip install mcp[cli] weave
    
  3. デモを実行します:
    python example_client.py example_server.py
    
    このコマンドにより、クライアントとサーバーの両方が起動します。クライアントでは対話型の CLI が起動し、さまざまな機能を試せます。

クライアント CLI コマンド

クライアントインターフェースは次のコマンドをサポートしています:
CommandDescription
tools利用可能なツールを一覧表示する
resources利用可能なリソースを一覧表示する
prompts利用可能なプロンプトを一覧表示する
add <a> <b>2 つの数値を加算する
bmi <weight> <height>BMI (体格指数) を計算する
weather <city>指定した都市の天気データを取得する
greeting <name>パーソナライズされたあいさつを取得する
user <id>ユーザーのプロフィールを取得する
configアプリの設定を取得する
code-review <code>コードレビュー用のプロンプトを生成する
debug <error>デバッグ用のプロンプトを生成する
demo利用可能な全機能のデモを実行します。各機能を順番に実行し、Weave UI でのやり取りの完全なトレースタイムラインを生成します。
qセッションを終了する

この例について

example_server.py サーバーでは、次のものを定義しています。
  • Tools: add()calculate_bmi()fetch_weather() などの関数
  • Resources: greeting://{name}config://appusers://{id}/profile のようなエンドポイント
  • Prompts: review_code()debug_error() のようなテンプレート
サーバー側のすべての操作は、weave.init() でクライアントを初期化すると、Weave によって自動的にトレースされます。 example_client.py クライアントでは、次の方法を示します。
  • MCP サーバーに接続する
  • 利用可能なツール、リソース、プロンプトを確認する
  • パラメーターを指定してツールを呼び出す
  • リソース URI を読み取る
  • 引数を使ってプロンプトを生成する
  • カスタムの method/function で weave.op() を使用する方法を示す
Weave はクライアント側のすべての call をトレースし、クライアントとサーバー間のやり取りの全体像を把握できるようにします。

FAQ

MCPトレースが必要な理由

LLMアプリケーションの開発者は、次の3つのカテゴリのいずれかに当てはまります。
  • MCPサーバー側の開発者: MCPクライアントに対して、複数のツール、リソース、プロンプトを公開したい場合です。既存のアプリケーションのツールやリソースなどを公開している、agent を構築している、またはオーケストレーター agent によって複数の agent を連携させているケースがこれに当たります。
  • MCPクライアント側の開発者: クライアント側のアプリケーションを複数のMCPサーバーに接続したい場合です。クライアント側ロジックの中核となるのは、どの tool を call するか、どのリソースを取得するかを判断するためのLLM callsです。
  • MCPサーバーおよびクライアントの開発者: サーバーとクライアントの両方を開発している場合です。
最初の2つのカテゴリのいずれかに当てはまる場合は、各 tool がいつ call されたか、実行フローがどうなっているか、token 数、さらにサーバーまたはクライアント側ロジック内のさまざまな components のレイテンシを把握したいはずです。 サーバーとクライアントの両方を開発している場合は、統合されたトレースタイムラインを確認できることで、サーバー側とクライアント側のロジックの両方をすばやく反復改善できます。 いずれの場合でも、可観測性レイヤーがあれば、次のことが可能になります。
  • アプリケーションをすばやく反復改善する
  • workflow や実行ロジックを監査する
  • ボトルネックを特定する