Analizzare le chiamate MCP utilizzando Trace

Cloud Trace raccoglie e visualizza dati, come chiamate di strumenti, invocazioni di metodi e prompt e risposte, per aiutarti a comprendere il comportamento delle tue applicazioni agentiche. Questo documento descrive come configurare un'applicazione agentica che chiama server MCP Google Cloud remoti per consentire a questi server di generare span che registrano lo stato delle chiamate.

Uno span registra una singola funzione o operazione che fa parte di un'operazione end-to-end più grande. Una traccia rappresenta una singola operazione end-to-end ed è composta da span. Pertanto, una traccia fornisce informazioni sulla sequenza di funzioni chiamate e sulla latenza complessiva, mentre uno span fornisce informazioni sullo stato e sulla latenza per una funzione specifica.

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 metodi API. Google Cloud 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 di traccia a un server MCP

Le pagine di riferimento 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 di 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 dello span di chiamata (PARENT_SPAN_ID).
  • Specifica 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 di 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 intervallo per un'operazione tools/call, ma non generano intervalli per altri tipi di operazioni o intervalli secondari per l'operazione tools/call.

  • I server MCP Google Cloud remoti generano uno span solo quando la richiesta è 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 il tracing. Descrive inoltre come i server MCP autogestiti possono generare intervalli di traccia.

Server self-hosted

Ti consigliamo di instrumentare i server MCP autogestiti 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 uno span di traccia per un'operazione tools/call:

Come configurare l'applicazione

Puoi utilizzare qualsiasi framework o SDK che trasmette il contesto di 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.

Come visualizzare gli intervalli

Per visualizzare i dati di traccia, utilizza Esplora tracce. Questa pagina 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 all'endpoint richiamato. Ad esempio, potrebbe essere qualcosa di simile a list_keys. Questa convenzione di denominazione è definita dalle Convenzioni semantiche OpenTelemetry per MCP.

Per trovare questi periodi, utilizza la barra dei filtri e aggiungi un filtro degli attributi per mcp.method.name. Imposta il valore del filtro su tools/call.

Esempi di instrumentazione

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

Gli esempi di instrumentazione che forniamo utilizzano OpenTelemetry: