Investigar chamadas do MCP usando o Trace

O Cloud Trace coleta e mostra dados, como chamadas de ferramentas, invocações de métodos, comandos e respostas, para ajudar você a entender o comportamento dos aplicativos generativos. Neste documento, descrevemos como configurar um aplicativo agêntico que chama servidores MCP remotos do Google Cloud para permitir que eles 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 de ponta a ponta maior. 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

Com as ferramentas, um agente pode coletar informações fora dos dados de treinamento, geralmente interagindo com APIs externas. Com os servidores MCP do Google Cloud, seus aplicativos de agente podem chamar ferramentas que invocam métodos da API Google Cloud . Por exemplo, seu aplicativo pode chamar a ferramenta list_log_entries para buscar dados de registros recentes.

O Protocolo de Contexto de Modelo (MCP) é uma especificação que define uma maneira padronizada de os agentes de IA se comunicarem e interagirem 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 deles, consulte Produtos compatíveis.

Como o contexto de rastreamento é transmitido para um servidor MCP

As páginas de referência do MCP, como a documentação de 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 campo _meta, que permite que clientes e servidores anexem metadados às interações. Os clientes e servidores podem usar esse campo para transmitir o contexto de rastreamento:

{
  "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 de _meta incluem um campo traceparent. O formato do valor desse campo é definido pelo cabeçalho traceparent do World Wide Web Consortium (W3C). 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 fez amostragem da solicitação (SAMPLED_FLAG). Esse campo tem um valor de 01 quando a amostragem é feita e 00 quando não é.

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

Limitações

  • O contexto de rastreamento precisa seguir o padrão W3C Trace Context, e a flag sampled precisa ser definida como 1.

  • Servidores remotos do Google Cloud MCP 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 remotos do Google e do Google Cloud MCP que oferecem suporte a traces

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

Como configurar o aplicativo

É possível usar qualquer framework ou SDK que transmita o contexto de rastreamento usando o campo _meta. Esses frameworks e SDKs incluem aqueles que são compatíveis com as Convenções semânticas do OpenTelemetry para MCP.

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

Como visualizar períodos

Para visualizar os dados de rastreamento, use o Explorador de rastreamentos. Nesta página, você pode conferir informações agregadas sobre seus dados de trace e analisar traces e intervalos individuais. Para saber mais, consulte Encontrar e analisar traces.

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

tools/call NAME

Na expressão anterior, NAME se refere ao endpoint invocado. Por exemplo, 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.

Amostras de instrumentação

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

As amostras de instrumentação que fornecemos usam o OpenTelemetry: