> ## Documentation Index
> Fetch the complete documentation index at: /docs/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, **Toqan Router** 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 instrumentation library they use.

### 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 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**](/docs/ai-studio/observability/traces.md) 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 for how to configure MCP tools on an agent.

### Externally instrumented MCP clients

Applications that use the MCP SDK directly can send traces to **Toqan Router** via OpenTelemetry. Instrument the MCP client with an OpenTelemetry instrumentation for the MCP SDK, then follow the [Observability quickstart](/docs/ai-studio/observability/quickstart.md) to point the OTLP exporter at `https://router.toqan.ai/eu/v2/otel` and authenticate with a **Toqan Router** API key.

The instrumentation library sets the `mcp.*` and `gen_ai.tool.*` attributes, 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](/docs/ai-studio/observability/traces.md): explore and filter traces
* [Span Attributes](/docs/ai-studio/observability/span-attributes.md): full attribute reference
* MCP Servers: register and configure MCP servers
* MCP Server tools: use MCP tools in agent requests


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.