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 agente. Este documento descreve como configurar um aplicativo de agente que chama servidores remotos do MCP do Google Cloud para permitir que esses servidores gerem intervalos que registram o status das chamadas.

Um intervalo registra uma única função ou operação que faz parte de uma operação completa maior. Um trace representa uma única operação completa 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 do MCP do Google Cloud, os aplicativos de agente 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 remotos do MCP 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 remotos do MCP do Google Cloud só geram um intervalo quando a solicitação é autenticada, autorizada e passa por outras verificações internas.

Servidores MCP que oferecem suporte ao rastreamento

Esta seção lista os servidores remotos do Google e do Google Cloud MCP que oferecem suporte ao rastreamento. Ela também descreve como os servidores MCP auto-hospedados podem gerar intervalos de trace.

Servidores auto-hospedados

Recomendamos que você instrumente os servidores MCP auto-hospedados para enviar dados de telemetria ao seu Google Cloud projeto. Se você usar o Python, a instrumentação poderá gerar intervalos para operações tools/call. Para mais informações, consulte Instrumentar um servidor MCP auto-hospedado com o OpenTelemetry.

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

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

É possível 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, é possível 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 remotos do MCP 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, 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: