MCP Tracing

When an agent calls an MCP server, Orq.ai captures the full lifecycle as a trace span. Each tool call becomes a span.tool child span under the agent step, with MCP-specific attributes that identify the server and the method called.

Trace MCP calls in spans

An agent with an MCP tool configured produces a trace like:

span.agent_execution
  └─ span.agent
       ├─ span.chat_completion   (model call)
       └─ span.tool              (MCP tool call)
            ├─ server: mcp.linear.app
            ├─ tool: create_issue
            ├─ arguments: { "title": "...", "teamId": "..." }
            ├─ result: { "id": "ENG-123", ... }
            └─ latency: 342ms

The span.tool span carries both GenAI tool attributes and MCP-specific attributes that identify the server and protocol details.

MCP span attributes

These attributes appear on span.tool spans where gen_ai.tool.type is "mcp". Platform-managed agents set that value themselves; externally instrumented clients get it from the OpenTelemetry MCP instrumentation library or equivalent.

MCP protocol attributes

Attribute	Description
`mcp.method.name`	MCP method called, e.g. `tools/call`, `tools/list`, `resources/read`
`mcp.session.id`	MCP session identifier. External instrumentation only; never set on platform-managed spans
`mcp.protocol.version`	MCP protocol version negotiated during initialization. Set by external instrumentation, and by the MCP gateway on its own spans
`mcp.resource.uri`	MCP resource URI, present on resource reads. External instrumentation only
`server.address`	MCP server hostname, e.g. `mcp.linear.app`. Platform-managed spans only; not retained on externally instrumented OTLP spans

GenAI tool attributes

These standard attributes carry the tool call details:

Attribute	Description
`gen_ai.tool.name`	Tool name as exposed to the model. Prefixed with the server key, e.g. `linear_mcp__create_issue`, when multiple MCP servers are configured
`gen_ai.tool.type`	`"mcp"` for MCP tool calls
`gen_ai.tool.description`	Tool description from the server’s tool catalog. External instrumentation only; never set on platform-managed spans
`gen_ai.tool.call.id`	Unique identifier for this tool call
`gen_ai.tool.call.arguments`	JSON-encoded arguments sent to the tool (sensitive content)
`gen_ai.tool.call.result`	JSON-encoded result returned by the tool (sensitive content)

On platform-managed spans, gen_ai.tool.call.arguments and gen_ai.tool.call.result are captured by default, with secret redaction and the Data Compliance masking rules applied before storage. Externally instrumented clients are not covered: masking runs only for spans that carry the orq.masking_options attribute, which platform components set, so values exported over OTLP are stored as received. Mask sensitive data before export.

Debug MCP calls

Find failing MCP calls

In the Traces panel:

Use the Status filter to scope to error traces
Open a failing trace and expand the span tree to find span.tool spans
Select a span.tool span and check the Attributes panel for gen_ai.tool.type and mcp.method.name to confirm it is an MCP call

Inspect a specific tool call

Open a trace with an MCP tool call and expand the span.tool span. The attributes panel shows the tool name, arguments, and result, plus the server address on platform-managed spans.

Trace a server-side issue

When the MCP server returns an error, the span.tool span ends with an error status and carries the error.type attribute. On platform-managed spans its value is the underlying error type rather than a fixed set of MCP error codes, so filter on span status instead of on a specific error.type value to find failed MCP calls.

Managed and external clients

Managed agents (platform-configured)

When an agent is configured with an MCP Server tool in AI Studio, the platform handles the MCP connection and automatically captures all tool call spans. No additional instrumentation is needed. See MCP Server tools for how to configure MCP tools on an agent.

Externally instrumented MCP clients

Applications that use the MCP SDK directly can send traces to Orq.ai via OpenTelemetry. Instrument the MCP client with the OpenTelemetry MCP instrumentation or equivalent, point the OTLP exporter at https://my.orq.ai/v2/otel, and authenticate with OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer <ORQ_API_KEY>" as the framework integrations do. The instrumentation library sets the mcp.* and gen_ai.tool.* attributes it defines, so external traces land in the same span tree shape. They can carry attributes that platform-managed spans do not, such as mcp.session.id, mcp.protocol.version, and mcp.resource.uri.

Traces: explore and filter traces
Span Attributes: full attribute reference
MCP Servers: register and configure MCP servers
MCP Server tools: use MCP tools in agent requests

Overview

Instrument your app

Explore

Monitor

Export

Review

Trace MCP calls in spans

MCP span attributes

MCP protocol attributes

GenAI tool attributes

Debug MCP calls

Find failing MCP calls

Inspect a specific tool call

Trace a server-side issue

Managed and external clients

Managed agents (platform-configured)

Externally instrumented MCP clients

​Trace MCP calls in spans

​MCP span attributes

​MCP protocol attributes

​GenAI tool attributes

​Debug MCP calls

​Find failing MCP calls

​Inspect a specific tool call

​Trace a server-side issue

​Managed and external clients

​Managed agents (platform-configured)

​Externally instrumented MCP clients

​Related

Trace MCP calls in spans

MCP span attributes

MCP protocol attributes

GenAI tool attributes

Debug MCP calls

Find failing MCP calls

Inspect a specific tool call

Trace a server-side issue

Managed and external clients

Managed agents (platform-configured)

Externally instrumented MCP clients

Related