Investigar chamadas do MCP usando o Trace

O Cloud Trace coleta e mostra dados, como chamadas de ferramentas, invocações de métodos e comandos e respostas, para ajudar você a entender o comportamento dos aplicativos de agentes. Este documento descreve como configurar um aplicativo agêntico que chama servidores MCP remotos do Google Cloud para permitir que esses servidores gerem períodos que registram o status das chamadas.

Um intervalo registra uma única função ou operação que faz parte de uma operação maior de ponta a ponta. Um trace representa uma única operação de ponta a ponta e é composto de intervalos. Portanto, um trace fornece informações sobre a sequência de chamadas de função e a latência geral, enquanto um período fornece informações de status e latência para uma função específica.

Sobre as ferramentas

As ferramentas permitem que um agente colete informações fora dos dados de treinamento, geralmente interagindo com APIs externas. Com os servidores MCP do Google Cloud, os aplicativos de agentes podem chamar ferramentas que invocam Google Cloud métodos invokeAPI. Por exemplo, o aplicativo pode chamar a ferramenta list_log_entries para buscar dados de registro recentes.

O Protocolo de Contexto de Modelo (MCP) é uma especificação que define uma maneira padronizada para que os agentes de IA se comuniquem e interajam com ferramentas, fontes de dados e recursos externos. Para uma lista completa de produtos que fornecem um servidor MCP e links para a documentação de referência, consulte Produtos compatíveis.

Como o contexto de trace é transmitido a um servidor MCP

As páginas de referência do MCP, como a documentação para list_log_entries, fornecem um exemplo de comando curl que pode ser usado para enviar solicitações HTTP à ferramenta. O payload JSON enviado na solicitação é semelhante a este:

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

O valor do campo name lista o nome da ferramenta, como list_log_entries. O campo arguments contém as informações necessárias para que a operação conclua a solicitação.

O padrão MCP define um _meta campo, que permite que clientes e servidores anexem metadados às interações. Clientes e servidores podem usar esse campo para transmitir o contexto de trace:

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

Os dados _meta incluem um campo traceparent. O formato do valor desse campo é definido pelo World Wide Web Consortium (W3C) traceparent cabeçalho. O valor inclui o seguinte:

  • Versão da especificação traceparent (00).
  • ID do trace (TRACE_ID).
  • ID do intervalo de chamada (PARENT_SPAN_ID).
  • Especifica se o período de chamada amostrou a solicitação (SAMPLED_FLAG). Este campo tem um valor de 01 quando amostrado e 00 quando não amostrado.

O campo tracestate contém informações de rastreamento específicas do fornecedor.

Limitações

  • O contexto de trace precisa seguir o padrão de contexto de trace do W3C, e o flag sampled precisa ser definido como 1.

  • Os servidores MCP remotos do Google Cloud podem gerar um único intervalo para uma operação tools/call, mas não geram intervalos para outros tipos de operações ou intervalos filhos para a operação tools/call.

  • Os servidores MCP remotos do Google Cloud só geram um intervalo quando a solicitação é autenticada, autorizada e passa por outras verificações internas.

Servidores MCP remotos do Google que oferecem suporte ao rastreamento Google Cloud

Os produtos a seguir contêm uma integração que permite que o servidor MCP remoto gere um intervalo de trace para uma operação tools/call:

Como configurar o aplicativo

Você pode usar qualquer framework ou SDK que transmita o contexto de trace usando o _meta campo. Esses frameworks e SDKs incluem aqueles que oferecem suporte às convenções semânticas do OpenTelemetry para MCP.

Por exemplo, você pode usar o framework do Kit de Desenvolvimento de Agente (ADK). Para saber mais, consulte Instrumentar aplicativos do ADK com o OpenTelemetry.

Como visualizar intervalos

Para visualizar os dados de trace, use o Explorador de traces. Essa página permite visualizar informações agregadas sobre os dados de trace e explorar traces e intervalos individuais. Para saber mais, consulte Encontrar e explorar traces.

Para visualizar intervalos gravados por servidores MCP, filtre os dados de trace pelo nome do intervalo. Por exemplo, alguns servidores MCP remotos do Google Cloud podem gerar um intervalo de trace quando recebem uma operação tools/call. Esses intervalos têm a seguinte convenção de nomenclatura:

tools/call NAME

Na expressão anterior, NAME se refere ao endpoint invocado. Por exemplo, isso pode ser algo semelhante a list_keys. Essa convenção de nomenclatura é definida pelas convenções semânticas do OpenTelemetry para MCP.

Para encontrar esses intervalos, use a barra de filtros e adicione um filtro de atributo para mcp.method.name. Defina o valor do filtro como tools/call.

Exemplos de instrumentação

Para recomendações de instrumentação, consulte Escolher uma abordagem de instrumentação.

Os exemplos de instrumentação que fornecemos usam OpenTelemetry: