Investigar chamadas do MCP usando o Trace

Com o Cloud Trace, é possível analisar o comportamento e o desempenho de aplicativos autônomos que chamam servidores MCP remotos do Google Cloud. É possível instrumentar seu aplicativo para gravar comandos, respostas e invocações de métodos, enquanto servidores MCP remotos geram intervalos para chamadas de ferramentas. Um trace captura a operação de ponta a ponta para mostrar sequências de chamadas e latência geral, enquanto períodos individuais fornecem detalhes de status e tempo para funções específicas.

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 para 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 traces:

{
  "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 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).
  • 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 traces precisa seguir o padrão W3C Trace Context, e a flag sampled precisa ser definida como 1.

  • 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 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 remotos do Google e do Google Cloud MCP que oferecem suporte ao rastreamento. Também descreve como seus servidores MCP autohospedados podem gerar intervalos de rastreamento.

Servidores auto-hospedados

Recomendamos instrumentar seus servidores MCP autohospedados para enviar dados de telemetria ao seu projeto Google Cloud . Se você usa Python, a instrumentação pode gerar intervalos para operações de tools/call. Para mais informações, consulte Instrumentar um servidor MCP autohospedado com o OpenTelemetry.

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

Os produtos a seguir têm uma integração que permite que o servidor MCP remoto gere um intervalo de rastreamento 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 da MCP da Análise de políticas
Unified Maintenance Referência da MCP do Unified Maintenance
Identity and Access Management Referência do MCP do Identity and Access Management
Serviço de política da organização Referência da MCP do serviço de política da organização
Spanner Referência do MCP do Spanner
Security Command Center Referência do MCP do Security Command Center

Configurar seu aplicativo

Você pode usar qualquer framework ou SDK que transmita o contexto de traces 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.

Ver períodos

Para visualizar os dados de trace, use o Explorador de traces. Nela, você pode conferir informações agregadas sobre seus dados de rastreamento e analisar traces e períodos 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 do Google Cloud podem gerar um intervalo de rastreamento 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 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 Ver chamadas para servidores MCP remotos.

Exemplos 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: