Investiga las llamadas de MCP con Trace

Puedes configurar tus aplicaciones de agente que llaman a servidores de MCP de Google Cloud remotos para permitir que esos servidores generen intervalos que registren el estado de las llamadas. Luego, puedes usar Cloud Trace, que almacena y analiza intervalos que registran llamadas a herramientas, invocaciones de métodos, instrucciones y respuestas, para ayudarte a comprender el comportamiento de tus aplicaciones de agente.

Un intervalo registra una sola función o una operación que forma parte de una operación integral más grande. Un seguimiento representa una sola operación integral y se compone de intervalos. Por lo tanto, un seguimiento proporciona información sobre la secuencia de funciones llamadas y la latencia general, mientras que un intervalo proporciona información sobre el estado y la latencia de una función específica.

Acerca de las herramientas

Las herramientas permiten que un agente recopile información fuera de sus datos de entrenamiento, por lo general, mediante la interacción con APIs externas. Con los servidores de MCP de Google Cloud, tus aplicaciones de agente pueden llamar a herramientas que invocan Google Cloud métodos invokeAPI. Por ejemplo, tu aplicación puede llamar a la herramienta list_log_entries para recuperar datos de registro recientes.

El Protocolo de contexto del modelo (MCP) es una especificación que define una forma estandarizada para que los agentes de IA se comuniquen e interactúen con herramientas, fuentes de datos y recursos externos. Para obtener una lista completa de los productos que proporcionan un servidor de MCP y vínculos a su documentación de referencia, consulta Productos compatibles.

Cómo se pasa el contexto de seguimiento a un servidor de MCP

Las páginas de referencia de MCP, como la documentación de list_log_entries, proporcionan un ejemplo curl command que puedes usar para enviar solicitudes HTTP a la herramienta. La carga útil de JSON que se envía en la solicitud es similar a la siguiente:

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

El valor del campo name muestra el nombre de la herramienta, como list_log_entries. El campo arguments contiene la información que requiere la operación para completar la solicitud.

El estándar de MCP define un campo _meta, que permite que los clientes y los servidores adjunten metadatos a sus interacciones. Los clientes y los servidores pueden usar este campo para pasar el contexto de seguimiento:

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

Los datos _meta incluyen un campo traceparent. El formato del valor de este campo se define mediante el World Wide Web Consortium (W3C) traceparent encabezado. El valor incluye lo siguiente:

  • Versión de la especificación traceparent (00).
  • Es el ID del seguimiento (TRACE_ID).
  • Es el ID del intervalo de llamada (PARENT_SPAN_ID).
  • Indica si el intervalo de llamada muestreó la solicitud (SAMPLED_FLAG). Este campo tiene un valor de 01 cuando se muestrea y 00 cuando no se muestrea.

El campo tracestate contiene información de seguimiento específica del proveedor.

Limitaciones

  • El contexto de seguimiento debe seguir el estándar W3C Trace Context, y la marca sampled debe establecerse en 1.

  • Los servidores de MCP de Google Cloud remotos pueden generar un solo intervalo para una operación tools/call, pero no generan intervalos para otros tipos de operaciones ni intervalos secundarios para la operación tools/call.

  • Los servidores de MCP de Google Cloud remotos generan un intervalo solo cuando la solicitud se autentica, se autoriza y pasa otras verificaciones internas.

Servidores de MCP que admiten el seguimiento

En esta sección, se enumeran los servidores de Google y Google Cloud MCP remotos que admiten el seguimiento. También se describe cómo tus servidores de MCP autoalojados pueden generar intervalos de seguimiento.

Servidores autoalojados

Te recomendamos que instrumentes tus servidores de MCP autoalojados para enviar datos de telemetría a tu Google Cloud proyecto. Si usas Python, la instrumentación puede generar intervalos para las operaciones tools/call. Para obtener más información, consulta Instrumenta un servidor de MCP autoalojado con OpenTelemetry.

Servidores de Google y Google Cloud MCP remotos que admiten el seguimiento

Los siguientes productos contienen una integración que permite que su servidor de MCP remoto genere un intervalo de seguimiento para una operación tools/call:

Producto Reference
Cloud Logging Referencia de MCP de Cloud Logging
Cloud Monitoring Referencia de MCP de Cloud Monitoring
Maps Grounding Lite Referencia de MCP de Maps Grounding Lite
GKE Referencia de MCP de GKE
Cloud Run Referencia de MCP de Cloud Run
Compute Engine Referencia de MCP de Compute Engine
Google Security Operations Referencia de MCP de Google SecOps
AlloyDB para PostgreSQL Referencia de MCP de AlloyDB para PostgreSQL
Agent Search Referencia de MCP de Agent Search
Cloud SQL
BigQuery Referencia de MCP de BigQuery
Personalized Service Health Referencia de MCP de Personalized Service Health
Facturación de Cloud Referencia de MCP de Facturación de Cloud
Solucionador de problemas de políticas Referencia de MCP del Solucionador de problemas de políticas

Configura tu aplicación

Puedes usar cualquier framework o SDK que pase el contexto de seguimiento con el _meta campo. Estos frameworks y SDKs incluyen aquellos que admiten las convenciones semánticas de OpenTelemetry para MCP.

Por ejemplo, puedes usar el framework del Kit de desarrollo de agentes (ADK). Para obtener más información, consulta Instrumenta aplicaciones de ADK con OpenTelemetry.

Visualiza intervalos

Para ver tus datos de seguimiento, usa el Explorador de seguimiento. Esta página te permite ver información agregada sobre tus datos de seguimiento y explorar intervalos y seguimientos individuales. Para obtener más información, consulta Busca y explora seguimientos.

Para ver los intervalos escritos por los servidores de MCP, filtra tus datos de seguimiento por el nombre del intervalo. Por ejemplo, algunos servidores de MCP de Google Cloud remotos pueden generar un intervalo de seguimiento cuando reciben una operación tools/call. Estos intervalos tienen la siguiente convención de nombres:

tools/call NAME

En la expresión anterior, NAME hace referencia a la herramienta invocada, por ejemplo, list_keys. Esta convención de nombres se define en las convenciones semánticas de OpenTelemetry para MCP.

Para encontrar estos intervalos, usa la barra de filtros y agrega un filtro de atributos para mcp.method.name. Establece el valor del filtro en tools/call. Para obtener información detallada sobre estos pasos, consulta Visualiza llamadas a servidores de MCP remotos.

Ejemplos de instrumentación

Para obtener recomendaciones de instrumentación, consulta Elige un enfoque de instrumentación.

En los ejemplos de instrumentación que proporcionamos, se usa OpenTelemetry: