> ## 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 chamadas de ferramentas MCP nos traces. Veja hostnames de servidores, nomes de ferramentas, argumentos, resultados, latência e erros de cada chamada do Model Context Protocol.

Quando um agente chama um servidor MCP, o **Toqan Router** captura todo o ciclo de vida como um span de trace. Cada chamada de ferramenta se torna um span filho `span.tool` sob a etapa do agente, com atributos específicos de MCP que identificam o servidor e o método chamado.

## Rastrear chamadas MCP em spans

Um agente com uma ferramenta MCP configurada gera um trace como este:

```
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
```

O span `span.tool` contém tanto atributos de ferramenta GenAI quanto atributos específicos de MCP que identificam o servidor e os detalhes do protocolo.

## Atributos de span MCP

Estes atributos aparecem em spans `span.tool` em que `gen_ai.tool.type` é `"mcp"`. Os agentes gerenciados pela plataforma definem esse valor por conta própria; clientes instrumentados externamente o recebem da biblioteca de instrumentação que utilizam.

### Atributos do protocolo MCP

| Atributo | Descrição |
| - | - |
| `mcp.method.name` | Método MCP chamado, por exemplo `tools/call`, `tools/list`, `resources/read` |
| `mcp.session.id` | Identificador da sessão MCP. Somente instrumentação externa; nunca é definido em spans gerenciados pela plataforma |
| `mcp.protocol.version` | Versão do protocolo MCP negociada durante a inicialização. Definido pela instrumentação externa e pelo gateway MCP em seus próprios spans |
| `mcp.resource.uri` | URI do recurso MCP, presente em leituras de recursos. Somente instrumentação externa |
| `server.address` | Hostname do servidor MCP, por exemplo `mcp.linear.app`. Somente spans gerenciados pela plataforma; não é mantido em spans OTLP instrumentados externamente |

### Atributos de ferramenta GenAI

Estes atributos padrão contêm os detalhes da chamada de ferramenta:

| Atributo | Descrição |
| - | - |
| `gen_ai.tool.name` | Nome da ferramenta conforme exposto ao modelo. Recebe como prefixo a chave do servidor, por exemplo `linear_mcp__create_issue`, quando vários servidores MCP estão configurados |
| `gen_ai.tool.type` | `"mcp"` para chamadas de ferramentas MCP |
| `gen_ai.tool.description` | Descrição da ferramenta no catálogo de ferramentas do servidor. Somente instrumentação externa; nunca é definido em spans gerenciados pela plataforma |
| `gen_ai.tool.call.id` | Identificador único desta chamada de ferramenta |
| `gen_ai.tool.call.arguments` | Argumentos codificados em JSON enviados à ferramenta (conteúdo sensível) |
| `gen_ai.tool.call.result` | Resultado codificado em JSON retornado pela ferramenta (conteúdo sensível) |

> [!NOTE]
>
> Em spans gerenciados pela plataforma, `gen_ai.tool.call.arguments` e `gen_ai.tool.call.result` são capturados por padrão, com a ocultação de segredos e as regras de mascaramento de Data Compliance aplicadas antes do armazenamento. Clientes instrumentados externamente não são abrangidos: o mascaramento só é executado em spans que contêm o atributo `orq.masking_options`, definido pelos componentes da plataforma, portanto os valores exportados por OTLP são armazenados como foram recebidos. Mascare os dados sensíveis antes da exportação.

## Depurar chamadas MCP

### Encontrar chamadas MCP com falha

No painel [**Traces**](/docs/pt-BR/ai-studio/observability/traces.md):

1. Use o filtro **Status** para restringir aos traces com erro
2. Abra um trace com falha e expanda a árvore de spans para encontrar os spans `span.tool`
3. Selecione um span `span.tool` e verifique `gen_ai.tool.type` e `mcp.method.name` no painel **Attributes** para confirmar que se trata de uma chamada MCP

### Inspecionar uma chamada de ferramenta específica

Abra um trace com uma chamada de ferramenta MCP e expanda o span `span.tool`. O painel de atributos mostra o nome da ferramenta, os argumentos e o resultado, além do endereço do servidor em spans gerenciados pela plataforma.

### Rastrear um problema no servidor

Quando o servidor MCP retorna um erro, o span `span.tool` termina com status de erro e contém o atributo `error.type`. Em spans gerenciados pela plataforma, seu valor é o tipo de erro subjacente, e não um conjunto fixo de códigos de erro MCP; por isso, filtre pelo status do span em vez de um valor específico de `error.type` para encontrar chamadas MCP com falha.

## Clientes gerenciados e externos

### Agentes gerenciados (configurados na plataforma)

Quando um agente é configurado com uma ferramenta MCP Server no **AI Studio**, a plataforma cuida da conexão MCP e captura automaticamente todos os spans de chamadas de ferramentas. Nenhuma instrumentação adicional é necessária.

Consulte Ferramentas MCP Server para saber como configurar ferramentas MCP em um agente.

### Clientes MCP instrumentados externamente

Aplicações que usam o SDK do MCP diretamente podem enviar traces para o **Toqan Router** via OpenTelemetry. Instrumente o cliente MCP com uma instrumentação do OpenTelemetry para o SDK do MCP e siga o [quickstart de Observability](/docs/pt-BR/ai-studio/observability/quickstart.md) para apontar o exportador OTLP para `https://router.toqan.ai/eu/v2/otel` e autenticar com uma chave de API do **Toqan Router**.

A biblioteca de instrumentação define os atributos `mcp.*` e `gen_ai.tool.*`, portanto os traces externos chegam com o mesmo formato de árvore de spans. Eles podem conter atributos que os spans gerenciados pela plataforma não têm, como `mcp.session.id`, `mcp.protocol.version` e `mcp.resource.uri`.

## Relacionados

* [Traces](/docs/pt-BR/ai-studio/observability/traces.md): explore e filtre traces
* [Span Attributes](/docs/pt-BR/ai-studio/observability/span-attributes.md): referência completa dos atributos
* MCP Servers: registre e configure servidores MCP
* Ferramentas MCP Server: use ferramentas MCP em solicitações de agentes


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