Google は AI 技術を使用して、コンテンツをご希望の言語に翻訳しています。AI 翻訳には誤りが含まれる場合があります。

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

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

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

ツールについて

ツールを使用すると、エージェントは通常、外部 API とのやり取りによって、トレーニングデータ以外の情報を収集できます。Google Cloud MCP サーバーを使用すると、エージェントアプリケーションは API メソッドを Google Cloud 呼び出すツールを呼び出すことができます。たとえば、アプリケーションは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 サーバーは、リクエストが認証、認可され、他の内部チェックに合格した場合にのみスパンを生成します。

トレースをサポートする MCP サーバー

このセクションでは、トレースをサポートするリモートの Google と Google Cloud MCP サーバーについて説明します。また、セルフホスト型 MCP サーバーでトレーススパンを生成する方法についても説明します。

セルフホスト型サーバー

セルフホスト型 MCP サーバーを計測して、テレメトリーデータを Google Cloud プロジェクトに送信することをおすすめします。 Python を使用する場合、計測では tools/call オペレーションのスパンを生成できます。詳細については、 OpenTelemetry を使用してセルフホスト型 MCP サーバーを計測するをご覧ください。

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

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

プロダクト	リファレンス
Cloud Logging	Cloud Logging MCP リファレンス
Cloud Monitoring	Cloud Monitoring MCP リファレンス
マップ Grounding Lite	マップ Grounding Lite MCP リファレンス
GKE	GKE MCP リファレンス
Cloud Run	Cloud Run MCP リファレンス
Compute Engine	Compute Engine MCP リファレンス
Google Security Operations	Google SecOps MCP リファレンス
AlloyDB for PostgreSQL	AlloyDB for PostgreSQL MCP リファレンス
エージェント検索	エージェント検索 MCP リファレンス
Cloud SQL	Cloud SQL for MySQL MCP リファレンス Cloud SQL for PostgreSQL MCP リファレンス Cloud SQL for SQL Server MCP リファレンス
BigQuery	BigQuery MCP リファレンス
Personalized Service Health	Personalized Service Health MCP リファレンス
Cloud Billing	Cloud Billing MCP リファレンス

アプリケーションを構成する方法

_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 を使用します。

コレクタベースのエクスポートを使用するサンプルについては、以下をご覧ください。
- Go
- Java
- Node.js
- Python
これらのサンプルは、トレースデータを Telemetry API に送信します。
トレースデータの直接エクスポートを使用して、そのデータを Telemetry API に送信する方法については、 Trace エクスポータから OTLP エンドポイントに移行するをご覧ください。
プロンプトとレスポンスを収集するようにエージェントアプリケーションを構成する方法を示すサンプルについては、生成 AI アプリケーションを計測する方法をご覧ください。

Trace を使用して MCP 呼び出しを調査する コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。