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 período para uma operação tools/call, mas não geram períodos para outros tipos de operações ou períodos 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 que oferecem suporte ao rastreamento

Esta seção lista os servidores Google Cloud MCP remotos do Google e 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 seus 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 MCP que oferecem suporte ao trace 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 seu 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 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: