Trace を使用して MCP 呼び出しを調査する

Cloud Trace は、ツール呼び出し、メソッド呼び出し、プロンプトとレスポンスなどのデータを収集して表示し、エージェント アプリケーションの動作を把握できるようにします。このドキュメントでは、リモート Google Cloud MCP サーバーを呼び出すエージェント アプリケーションを構成して、これらのサーバーが呼び出しのステータスを記録するスパンを生成できるようにする方法について説明します。

スパンは、より大きなエンドツーエンドのオペレーションの一部である単一の関数またはオペレーションを記録します。トレースは、単一のエンドツーエンドのオペレーションを表し、スパンで構成されます。したがって、トレースは呼び出された関数のシーケンスと全体的なレイテンシに関する情報を提供し、スパンは特定の関数のステータスとレイテンシに関する情報を提供します。

ツールについて

ツールを使用すると、エージェントは通常、外部 API とのやり取りによって、トレーニング データ以外の情報を収集できます。Google Cloud MCP サーバーを使用すると、エージェント アプリケーションは Google Cloud API メソッドを呼び出すツールを呼び出すことができます。たとえば、アプリケーションで list_log_entries ツールを呼び出して、最近のログデータを取得できます。

Model Context Protocol（MCP）は、AI エージェントが外部のツール、データソース、リソースと通信してやり取りするための標準化された方法を定義する仕様です。MCP サーバーを提供するプロダクトと、そのリファレンス ドキュメントへのリンクの完全なリストについては、サポートされているプロダクトをご覧ください。

トレース コンテキストが MCP サーバーに渡される方法

list_log_entries のドキュメントなどの MCP リファレンス ページには、ツールに HTTP リクエストを送信するために使用できる curl コマンドの例が記載されています。リクエストで送信される JSON ペイロードは次のようになります。

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "NAME",
    "arguments": {
      // provide these details according to the tool's MCP specification
    }
  },
  "id": 1
}

name フィールドの値には、list_log_entries などのツール名が一覧表示されます。arguments フィールドには、リクエストを完了するためにオペレーションで必要な情報が含まれます。

MCP 標準では、クライアントとサーバーがメタデータをやり取りに関連付けることができる _meta フィールドが定義されています。クライアントとサーバーは、このフィールドを使用してトレース コンテキストを渡すことができます。

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "NAME",
    "arguments": {
      // provide these details according to the tool's MCP specification
    }
    "_meta": {
        "traceparent": "00-TRACE_ID-PARENT_SPAN_ID-SAMPLED_FLAG"
        "tracestate": "Vendor specific information."
      }
  },
  "id": 1
}

_meta データには、traceparent フィールドが含まれています。このフィールドの値の形式は、World Wide Web Consortium（W3C）の traceparent ヘッダーで定義されています。値には次のものが含まれます。

  • traceparent 仕様のバージョン（00）。
  • トレースの ID（TRACE_ID）。
  • 呼び出し元スパンの ID（PARENT_SPAN_ID）。
  • 呼び出し元スパンがリクエストをサンプリングしたかどうかを指定します（SAMPLED_FLAG）。このフィールドの値は、サンプリングされた場合は 01、サンプリングされなかった場合は 00 になります。

tracestate フィールドには、ベンダー固有のトレース情報が含まれます。

制限事項

  • トレース コンテキストは W3C トレース コンテキスト標準に準拠し、sampled フラグを 1 に設定する必要があります。

  • リモートの Google Cloud MCP サーバーは、tools/call オペレーションの単一スパンを生成できますが、他のタイプのオペレーションのスパンや tools/call オペレーションの子スパンは生成しません。

  • リモート Google Cloud MCP サーバーは、リクエストが認証、認可され、他の内部チェックに合格した場合にのみスパンを生成します。

トレースをサポートするリモート Google と Google Cloud MCP サーバー

次のプロダクトには、リモート MCP サーバーが tools/call オペレーションのトレース スパンを生成できるインテグレーションが含まれています。

アプリケーションの構成方法

_meta フィールドを使用してトレース コンテキストを渡すフレームワークまたは SDK を使用できます。これらのフレームワークと SDK には、MCP の OpenTelemetry セマンティック規約をサポートするものが含まれます。

たとえば、Agent Development Kit（ADK）フレームワークを使用できます。詳細については、OpenTelemetry を使用して ADK アプリケーションを計測するをご覧ください。

スパンを表示する方法

トレースデータを表示するには、Trace エクスプローラを使用します。このページでは、トレースデータの集計情報を表示し、個々のトレースとスパンを調べることができます。詳細については、トレースを検索して調査するをご覧ください。

MCP サーバーによって書き込まれたスパンを表示するには、スパン名でトレースデータをフィルタします。たとえば、一部のリモート Google Cloud MCP サーバーは、tools/call オペレーションを受信するとトレース スパンを生成できます。これらのスパンには、次の命名規則が適用されます。

tools/call NAME

上記の式で、NAME は呼び出されたエンドポイントを参照します。たとえば、list_keys のようなものになります。この命名規則は、MCP の OpenTelemetry セマンティック規約で定義されています。

これらのスパンを見つけるには、フィルタバーを使用して、mcp.method.name の属性フィルタを追加します。フィルタの値を tools/call に設定します。

インストルメンテーションのサンプル

計測手法の推奨事項については、計測方法を選択するをご覧ください。

提供するインストルメンテーションのサンプルでは、OpenTelemetry を使用しています。

  • コレクタベースのエクスポートを使用するサンプルについては、以下をご覧ください。

    これらのサンプルは、トレースデータを Telemetry API に送信します。

  • トレースデータの直接エクスポートを使用して、そのデータを Telemetry API に送信する方法については、Trace エクスポータから OTLP エンドポイントに移行するをご覧ください。

  • プロンプトとレスポンスを収集するようにエージェント アプリケーションを構成する方法を示すサンプルについては、生成 AI アプリケーションを計測する方法をご覧ください。

  • トレース生成をサポートするリモート Google Cloud MCP サーバーと、これらのサーバーにスパンの作成を指示するようにアプリケーションを構成する方法については、Trace を使用して MCP 呼び出しを調査するをご覧ください。