Investigar chamadas do MCP usando o Trace

É possível configurar seus aplicativos de agente que chamam servidores MCP remotos do Google Cloud para permitir que esses servidores gerem intervalos que registram o status das chamadas. Em seguida, use o Cloud Trace, que armazena e analisa intervalos que registram chamadas de ferramentas, invocações de métodos e comandos e respostas, para entender o comportamento dos aplicativos de agente.

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 funções chamadas 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 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 de list_log_entries, fornecem um exemplo curl comando 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).
  • Se o período de chamada amostrou a solicitação (SAMPLED_FLAG). Esse 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 geram um intervalo somente 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 instrumentar 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 Google Cloud MCP remotos do Google e 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:

Produto Referência
Cloud Logging Referência do MCP do Cloud Logging
Cloud Monitoring Referência do MCP do Cloud Monitoring
Grounding Lite do Maps Referência do MCP do Grounding Lite do Maps
GKE Referência do MCP do GKE
Cloud Run Referência do MCP do Cloud Run
Compute Engine Referência do MCP do Compute Engine
Google Security Operations Referência do MCP do Google SecOps
AlloyDB para PostgreSQL Referência do MCP do AlloyDB para PostgreSQL
Agent Search Referência do MCP do Agent Search
Cloud SQL
BigQuery Referência do MCP do BigQuery
Personalized Service Health Referência do MCP do Personalized Service Health
Cloud Billing Referência do MCP do Cloud Billing
Solucionador de problemas de políticas Referência do MCP do Solucionador de problemas de políticas

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.

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 à ferramenta invocada, por exemplo, 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 filtro e adicione um filtro de atributo para mcp.method.name. Defina o valor do filtro como tools/call. Para informações detalhadas sobre essas etapas, consulte Visualizar chamadas para servidores MCP remotos.

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: