Investiga las llamadas de MCP con Trace

Cloud Trace recopila y muestra datos, como llamadas a herramientas, invocaciones de métodos, instrucciones y respuestas, para ayudarte a comprender el comportamiento de tus aplicaciones de agentes. En este documento, se describe cómo configurar una aplicación agente que llama a servidores MCP remotos de Google Cloud para permitir que estos servidores generen intervalos que registren el estado de las llamadas.

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 de estado y latencia para 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 MCP de Google Cloud, tus aplicaciones de agentes pueden llamar a herramientas que invocan métodos Google Cloud 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 MCP y vínculos a su documentación de referencia, consulta Productos compatibles.

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

Las páginas de referencia de MCP, como la documentación de list_log_entries, proporcionan un comando curl de ejemplo 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 MCP define un campo _meta field, 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).
  • ID del seguimiento (TRACE_ID).
  • ID del intervalo de llamada (PARENT_SPAN_ID).
  • Especifica 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 MCP remotos de Google Cloud 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 MCP remotos de Google Cloud solo generan un intervalo cuando la solicitud se autentica, autoriza y pasa otras verificaciones internas.

Servidores MCP que admiten el seguimiento

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

Servidores autoalojados

Te recomendamos que instrumentes tus servidores 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 MCP autoalojado con OpenTelemetry.

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

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

Cómo configurar 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.

Cómo ver 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 seguimientos e intervalos individuales. Para obtener más información, consulta Cómo encontrar y explorar seguimientos.

Para ver los intervalos escritos por los servidores MCP, filtra tus datos de seguimiento por el nombre del intervalo. Por ejemplo, algunos servidores MCP remotos de Google Cloud 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 al extremo invocado. Por ejemplo, podría ser algo similar a 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 atributo para mcp.method.name. Establece el valor del filtro en tools/call.

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: