MCP-Aufrufe mit Trace untersuchen

Cloud Trace erfasst und zeigt Daten wie Toolaufrufe, Methodenaufrufe sowie Prompts und Antworten an, damit Sie das Verhalten Ihrer Agentenanwendungen besser verstehen. In diesem Dokument wird beschrieben, wie Sie eine Agentenanwendung konfigurieren, die Remote-MCP-Server (Model Context Protocol) von Google Cloud aufruft, damit diese Server Spans generieren können, in denen der Status der Aufrufe aufgezeichnet wird.

Ein Span zeichnet eine einzelne Funktion oder einen einzelnen Vorgang auf, der Teil eines größeren End-to-End-Vorgangs ist. Ein Trace stellt einen einzelnen End-to-End-Vorgang dar und besteht aus Spans. Ein Trace enthält daher Informationen zur Reihenfolge der aufgerufenen Funktionen und zur Gesamtlatenz, während ein Span Status- und Latenzinformationen für eine bestimmte Funktion enthält.

Tools

Mit Tools kann ein Agent Informationen außerhalb seiner Trainingsdaten erfassen, in der Regel durch Interaktion mit externen APIs. Mit Google Cloud-MCP-Servern können Ihre Agentenanwendungen Tools aufrufen, die Google Cloud API-Methoden aufrufen. Ihre Anwendung kann beispielsweise das Tool list_log_entries aufrufen, um aktuelle Logdaten abzurufen.

Das Model Context Protocol (MCP) ist eine Spezifikation, die eine standardisierte Möglichkeit für KI-Agenten definiert, mit externen Tools, Datenquellen und Ressourcen zu kommunizieren und zu interagieren. Eine vollständige Liste der Produkte die einen MCP-Server bereitstellen, und Links zur zugehörigen Referenzdokumentation finden Sie unter Unterstützte Produkte.

Trace-Kontext an einen MCP-Server übergeben

Auf MCP-Referenzseiten wie der Dokumentation für list_log_entries finden Sie ein Beispiel für einen curl-Befehl , mit dem Sie HTTP-Anfragen an das Tool senden können. Die in der Anfrage gesendete JSON-Nutzlast sieht so aus:

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

Der Wert des Felds name enthält den Toolnamen, z. B. list_log_entries. Das Feld arguments enthält die Informationen, die für den Vorgang erforderlich sind, um die Anfrage abzuschließen.

Der MCP-Standard definiert ein _meta Feld, mit dem Clients und Server Metadaten an ihre Interaktionen anhängen können. Clients und Server können dieses Feld verwenden, um den Trace-Kontext zu übergeben:

{
  "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
}

Die _meta-Daten enthalten ein Feld traceparent. Das Format des Werts dieses Felds wird durch den World Wide Web Consortium (W3C) traceparent Header definiert. Der Wert enthält Folgendes:

  • Version der traceparent-Spezifikation (00).
  • ID des Trace (TRACE_ID).
  • ID des aufrufenden Spans (PARENT_SPAN_ID).
  • Gibt an, ob der aufrufende Span die Anfrage erfasst hat (SAMPLED_FLAG). Dieses Feld hat den Wert 01, wenn die Anfrage erfasst wurde, und 00, wenn nicht.

Das Feld tracestate enthält anbieterspezifische Trace-Informationen.

Beschränkungen

  • Der Trace-Kontext muss dem W3C Trace Context-Standard entsprechen, und das sampled Flag muss auf 1 gesetzt sein.

  • Remote-MCP-Server von Google Cloud können einen einzelnen Span für einen tools/call-Vorgang generieren, aber keine Spans für andere Vorgangstypen oder untergeordnete Spans für den tools/call-Vorgang.

  • Remote-MCP-Server von Google Cloud generieren nur dann einen Span, wenn die Anfrage authentifiziert und autorisiert ist und andere interne Prüfungen bestanden hat.

MCP-Server, die Tracing unterstützen

In diesem Abschnitt werden die Remote-Google- und Google Cloud MCP-Server aufgeführt, die Tracing unterstützen. Außerdem wird beschrieben, wie Ihre selbst gehosteten MCP-Server Trace-Spans generieren können.

Selbst gehostete Server

Wir empfehlen, Ihre selbst gehosteten MCP-Server so zu instrumentieren, dass Telemetriedaten an Ihr Google Cloud Projekt gesendet werden. Wenn Sie Python verwenden, kann die Instrumentierung Spans für tools/call-Vorgänge generieren. Weitere Informationen finden Sie unter Selbst gehosteten MCP-Server mit OpenTelemetry instrumentieren.

Remote-MCP-Server von Google und Google Cloud MCP, die Tracing unterstützen

Die folgenden Produkte enthalten eine Integration, mit der ihr Remote-MCP-Server einen Trace-Span für einen tools/call-Vorgang generieren kann:

Anwendung konfigurieren

Sie können jedes Framework oder SDK verwenden, das den Trace-Kontext über das _meta Feld übergibt. Dazu gehören Frameworks und SDKs, die die OpenTelemetry Semantic Conventions für MCP unterstützen.

Sie können beispielsweise das Agent Development Kit (ADK) Framework verwenden. Weitere Informationen finden Sie unter ADK-Anwendungen mit OpenTelemetry instrumentieren.

Spans ansehen

Verwenden Sie den Trace Explorer, um Ihre Trace-Daten aufzurufen. Auf dieser Seite können Sie aggregierte Informationen zu Ihren Trace-Daten aufrufen und einzelne Traces und Spans untersuchen. Weitere Informationen finden Sie unter Traces suchen und untersuchen.

Wenn Sie Spans aufrufen möchten, die von MCP-Servern geschrieben wurden, filtern Sie Ihre Trace-Daten nach dem Spannamen. Einige Remote-MCP-Server von Google Cloud können beispielsweise einen Trace-Span generieren, wenn sie einen tools/call-Vorgang empfangen. Diese Spans haben die folgende Namenskonvention:

tools/call NAME

Im vorherigen Ausdruck bezieht sich NAME auf den aufgerufenen Endpunkt. Das kann beispielsweise list_keys sein. Diese Namens konvention wird durch die OpenTelemetry Semantic Conventions für MCP definiert.

Verwenden Sie die Filterleiste und fügen Sie einen Attributfilter für mcp.method.name hinzu, um diese Spans zu finden. Legen Sie den Wert des Filters auf tools/call fest.

Instrumentierungsbeispiele

Empfehlungen zur Instrumentierung finden Sie unter Instrumentierungsansatz auswählen.

In den von uns bereitgestellten Instrumentierungsbeispielen wird OpenTelemetry verwendet: