Analizzare le chiamate MCP utilizzando Trace

Cloud Trace ti consente di analizzare il comportamento e le prestazioni delle applicazioni agenti che chiamano server MCP Google Cloud remoti. Puoi instrumentare la tua applicazione per registrare prompt, risposte e chiamate di metodi, mentre i server MCP remoti generano gli span per le chiamate agli strumenti. Una traccia acquisisce l'operazione end-to-end per mostrare le sequenze di chiamate e la latenza complessiva, mentre i singoli intervalli forniscono dettagli su stato e tempistiche per funzioni specifiche.

Informazioni sugli strumenti

Gli strumenti consentono a un agente di raccogliere informazioni al di fuori dei dati di addestramento, in genere interagendo con API esterne. Con i server MCP di Google Cloud, le tue applicazioni agentic possono chiamare strumenti che richiamano Google Cloud metodi API. Ad esempio, la tua applicazione può chiamare lo strumento list_log_entries per recuperare i dati dei log recenti.

Il Model Context Protocol (MCP) è una specifica che definisce un modo standardizzato per gli agenti AI di comunicare e interagire con strumenti, origini dati e risorse esterni. Per un elenco completo dei prodotti che forniscono un server MCP e link alla relativa documentazione di riferimento, consulta Prodotti supportati.

Come viene passato il contesto della traccia a un server MCP

Le pagine di riferimento di MCP, come la documentazione per list_log_entries, forniscono un comando curl di esempio che puoi utilizzare per inviare richieste HTTP allo strumento. Il payload JSON inviato nella richiesta è simile al seguente:

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

Il valore del campo name elenca il nome dello strumento, ad esempio list_log_entries. Il campo arguments contiene le informazioni richieste dall'operazione per completare la richiesta.

Lo standard MCP definisce un campo _meta, che consente a client e server di allegare metadati alle loro interazioni. Client e server possono utilizzare questo campo per passare il contesto della traccia:

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

I dati _meta includono un campo traceparent. Il formato del valore di questo campo è definito dall'intestazione traceparent del World Wide Web Consortium (W3C). Il valore include quanto segue:

  • Versione della specifica traceparent (00).
  • ID della traccia (TRACE_ID).
  • ID dell'intervallo di chiamata (PARENT_SPAN_ID).
  • Indica se lo span chiamante ha campionato la richiesta (SAMPLED_FLAG). Questo campo ha un valore di 01 se campionato e 00 se non campionato.

Il campo tracestate contiene informazioni di tracciamento specifiche del fornitore.

Limitazioni

  • Il contesto della traccia deve rispettare lo standard W3C Trace Context e il flag sampled deve essere impostato su 1.

  • I server MCP di Google Cloud remoti possono generare un singolo span per un'operazione tools/call, ma non generano span per altri tipi di operazioni o span secondari per l'operazione tools/call.

  • I server MCP Google Cloud remoti generano uno span solo quando la richiesta viene autenticata, autorizzata e supera altri controlli interni.

Server MCP che supportano la tracciabilità

Questa sezione elenca i server Google e Google Cloud MCP remoti che supportano la tracciabilità. Descrive inoltre come i server MCP autogestiti possono generare intervalli di traccia.

Server self-hosted

Ti consigliamo di instrumentare i server MCP self-hosted per inviare dati di telemetria al tuo progetto Google Cloud . Se utilizzi Python, la strumentazione può generare span per le operazioni tools/call. Per saperne di più, consulta Strumentare un server MCP autogestito con OpenTelemetry.

Server Google e Google Cloud MCP remoti che supportano la tracciabilità

I seguenti prodotti contengono un'integrazione che consente al server MCP remoto di generare un intervallo di traccia per un'operazione tools/call:

Prodotto Riferimento
Cloud Logging Riferimento MCP di Cloud Logging
Cloud Monitoring Riferimento MCP di Cloud Monitoring
Maps Grounding Lite Riferimento MCP di Maps Grounding Lite
GKE Riferimento MCP di GKE
Cloud Run Riferimento MCP Cloud Run
Compute Engine Riferimento MCP di Compute Engine
Google Security Operations Riferimento a Google SecOps MCP
AlloyDB per PostgreSQL Riferimento MCP di AlloyDB per PostgreSQL
Agent Search Riferimento MCP di Agent Search
Cloud SQL
BigQuery Riferimento a BigQuery MCP
Personalized Service Health Riferimento MCP di Personalized Service Health
Cloud Billing Riferimento MCP per la fatturazione Cloud
Policy Troubleshooter Policy Troubleshooter MCP reference
Managed Service for Apache Airflow Riferimento MCP di Managed Service for Apache Airflow
Datastream Riferimento MCP di Datastream
Policy Analyzer Riferimento MCP di Policy Analyzer
Unified Maintenance Riferimento MCP di Unified Maintenance
Identity and Access Management Identity and Access Management MCP reference
Servizio Policy dell'organizzazione Guida di riferimento al servizio Policy dell'organizzazione MCP
Spanner Riferimento MCP di Spanner
Security Command Center Riferimento MCP di Security Command Center

Configura la tua applicazione

Puoi utilizzare qualsiasi framework o SDK che trasmette il contesto della traccia utilizzando il campo _meta. Questi framework e SDK includono quelli che supportano le convenzioni semantiche OpenTelemetry per MCP.

Ad esempio, puoi utilizzare il framework Agent Development Kit (ADK). Per scoprire di più, consulta Instrumentare le applicazioni ADK con OpenTelemetry.

Visualizzare gli intervalli

Per visualizzare i dati di traccia, utilizza Esplora tracce. Questa pagina ti consente di visualizzare informazioni aggregate sui dati di traccia ed esplorare singole tracce e intervalli. Per saperne di più, consulta Trovare ed esplorare le tracce.

Per visualizzare gli intervalli scritti dai server MCP, filtra i dati di traccia in base al nome dell'intervallo. Ad esempio, alcuni server MCP di Google Cloud remoti possono generare uno span di traccia quando ricevono un'operazione tools/call. Questi intervalli hanno la seguente convenzione di denominazione:

tools/call NAME

Nell'espressione precedente, NAME si riferisce allo strumento richiamato, ad esempio list_keys. Questa convenzione di denominazione è definita dalle convenzioni semantiche di OpenTelemetry per MCP.

Per trovare questi intervalli, utilizza la barra dei filtri e aggiungi un filtro degli attributi per mcp.method.name. Imposta il valore del filtro su tools/call. Per informazioni dettagliate su questi passaggi, vedi Visualizzare le chiamate ai server MCP remoti.

Campioni di strumentazione

Per i consigli sull'instrumentazione, vedi Scegliere un approccio di instrumentazione.

Gli esempi di instrumentazione che forniamo utilizzano OpenTelemetry: