Investigar chamadas do MCP usando o Trace

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

Um período 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 períodos. 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 do MCP no 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 período 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 a flag sampled precisa ser definida como 1.

  • Os servidores remotos do MCP no 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 remotos do MCP no Google Cloud geram um período 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 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 períodos 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 períodos 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 período 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
Serviço gerenciado para Apache Airflow Referência do MCP do Serviço gerenciado para Apache Airflow
Datastream Referência do MCP do Datastream
Analisador de políticas Referência do MCP do Analisador 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 períodos

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 períodos individuais. Para saber mais, consulte Encontrar e explorar traces.

Para visualizar períodos gravados por servidores MCP, filtre os dados de trace pelo nome do período. Por exemplo, alguns servidores remotos do MCP no Google Cloud podem gerar um período de trace 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 à ferramenta invocada, por exemplo, list_keys. Essa convenção de nomenclatura é definida pelas convenções semânticas do OpenTelemetry para MCP.

Para encontrar esses períodos, 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 remotos do MCP.

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: