> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orq.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Tracing

> Observe MCP tool calls in traces. See server hostnames, tool names, arguments, results, latency, and errors for every Model Context Protocol call.

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](https://www.npmjs.com/package/@opentelemetry/instrumentation-mcp) 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)                                                                               |

<Note>
  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](/ai-studio/organization/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.
</Note>

## Debug MCP calls

### Find failing MCP calls

In the [**Traces**](/ai-studio/observability/traces) panel:

1. Use the **Status** filter to scope to error traces
2. Open a failing trace and expand the span tree to find `span.tool` spans
3. 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](/ai-studio/ai-engineering/run-agents) 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](https://www.npmjs.com/package/@opentelemetry/instrumentation-mcp) 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](/ai-studio/integrations/frameworks/openai) 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`.

## Related

* [Traces](/ai-studio/observability/traces): explore and filter traces
* [Span Attributes](/ai-studio/observability/span-attributes): full attribute reference
* [MCP Servers](/ai-studio/ai-engineering/create-tools#mcp-servers): register and configure MCP servers
* [MCP Server tools](/ai-studio/ai-engineering/run-agents): use MCP tools in agent requests