MCP Tracing

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)

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:

Use o filtro Status para restringir aos traces com erro
Abra um trace com falha e expanda a árvore de spans para encontrar os spans span.tool
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 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.

Traces: explore e filtre traces
Span Attributes: referência completa dos atributos
MCP Servers: registre e configure servidores MCP
Ferramentas MCP Server: use ferramentas MCP em solicitações de agentes

Visão geral

Instrumente seu app

Explorar

Monitorar

Exportar

Revisar

Privacidade e segurança de dados

Integrações com frameworks

Rastrear chamadas MCP em spans

Atributos de span MCP

Atributos do protocolo MCP

Atributos de ferramenta GenAI

Depurar chamadas MCP

Encontrar chamadas MCP com falha

Inspecionar uma chamada de ferramenta específica

Rastrear um problema no servidor

Clientes gerenciados e externos

Agentes gerenciados (configurados na plataforma)

Clientes MCP instrumentados externamente

​Rastrear chamadas MCP em spans

​Atributos de span MCP

​Atributos do protocolo MCP

​Atributos de ferramenta GenAI

​Depurar chamadas MCP

​Encontrar chamadas MCP com falha

​Inspecionar uma chamada de ferramenta específica

​Rastrear um problema no servidor

​Clientes gerenciados e externos

​Agentes gerenciados (configurados na plataforma)

​Clientes MCP instrumentados externamente

​Relacionados

Rastrear chamadas MCP em spans

Atributos de span MCP

Atributos do protocolo MCP

Atributos de ferramenta GenAI

Depurar chamadas MCP

Encontrar chamadas MCP com falha

Inspecionar uma chamada de ferramenta específica

Rastrear um problema no servidor

Clientes gerenciados e externos

Agentes gerenciados (configurados na plataforma)

Clientes MCP instrumentados externamente

Relacionados