Investigate MCP calls using Trace

Cloud Trace collects and displays data, such as tool calls, method invocations, and prompts and responses, to help you understand the behavior of your agentic applications. This document describes how to configure an agentic application that calls remote Google Cloud MCP servers to enable these servers to generate spans that record the status of the calls.

A span records a single function or operation that is part of a larger end-to-end operation. A trace represents a single end-to-end operation and is composed of spans. Therefore, a trace provides information about the sequence of functions called and overall latency while a span provides status and latency information for a specific function.

About tools

Tools let an agent gather information outside of its training data, typically by interacting with external APIs. With Google Cloud MCP servers, your agentic applications can call tools that invoke Google Cloud API methods. For example, your application can call the list_log_entries tool to fetch recent log data.

The Model Context Protocol (MCP) is a specification that defines a standardized way for AI agents to communicate and interact with external tools, data sources, and resources. For a complete list of products that provide an MCP server and links to their reference documentation, see Supported products.

How trace context is passed to a MCP server

MCP reference pages, such as the documentation for list_log_entries, provide an example curl command that you can use to to send HTTP requests to the tool. The JSON payload sent in the request is similar to the following:

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "NAME",
    "arguments": {
      // provide these details according to the tool's MCP specification
    }
  },
  "id": 1
}

The value of the name field lists the tool name, such as list_log_entries. The arguments field contains the information required by the operation to complete the request.

The MCP standard defines a _meta field, which lets clients and servers attach metadata to their interactions. Clients and servers can use this field to pass the trace context:

{
  "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
}

The _meta data includes a traceparent field. The format of the value of this field is defined by the World Wide Web Consortium (W3C) traceparent header. The value includes the following:

  • Version of the traceparent specification (00).
  • ID of the trace (TRACE_ID).
  • ID of the calling span (PARENT_SPAN_ID).
  • Specifies whether the calling span sampled the request (SAMPLED_FLAG). This field has a value of 01 when sampled and 00 when not sampled.

The tracestate field carries vendor-specific tracing information.

Limitations

  • The trace context must follow the W3C Trace Context standard, and the sampled flag must be set to 1.

  • Remote Google Cloud MCP servers can generate a single span for a tools/call operation, but it doesn't generate spans for other types of operations or child spans for the tools/call operation.

  • Remote Google Cloud MCP servers only generate a span when the request is authenticated, authorized, and passes other internal checks.

MCP servers that support tracing

This section lists the remote Google and Google Cloud MCP servers that support tracing. It also describes how your self-hosted MCP servers can generate trace spans.

Self-hosted servers

We recommend that you instrument your self-hosted MCP servers to send telemetry data to your Google Cloud project. If you use Python, then the instrumentation can generate spans for tools/call operations. For more information, see Instrument a self-hosted MCP server with OpenTelemetry.

Remote Google and Google Cloud MCP servers that support tracing

The following products contain an integration that lets their remote MCP server generate a trace span for a tools/call operation:

Product Reference
Cloud Logging Cloud Logging MCP reference
Cloud Monitoring Cloud Monitoring MCP reference
Maps Grounding Lite Maps Grounding Lite MCP reference
GKE GKE MCP reference
Cloud Run Cloud Run MCP reference
Compute Engine Compute Engine MCP reference
Google Security Operations Google SecOps MCP reference
AlloyDB for PostgreSQL AlloyDB for PostgreSQL MCP reference
Agent Search Agent Search MCP reference

How to configure your application

You can use any framework or SDK that passes the trace context using the _meta field. These frameworks and SDKs include those that support the OpenTelemetry Semantic Conventions for MCP.

For example, you can use the Agent Development Kit (ADK) framework. To learn more, see Instrument ADK applications with OpenTelemetry.

How to view spans

To view your trace data, use Trace Explorer. This page lets you view aggregate information about your trace data and explore individual traces and spans. To learn more, see Find and explore traces.

To view spans written by MCP servers, filter your trace data by the span name. For example, some remote Google Cloud MCP servers can generate a trace span when they receive a tools/call operation. These spans have the following naming convention:

tools/call NAME

In the previous expression, NAME refers to the invoked endpoint. For example, this might be something similar to list_keys. This naming convention is defined by the OpenTelemetry Semantic Conventions for MCP.

To find these spans, use the filter bar and add an attribute filter for mcp.method.name. Set the value of the filter to tools/call.

Instrumentation samples

For instrumentation recommendations, see Choose an instrumentation approach.

The instrumentation samples we provide use OpenTelemetry: