analisar-mcp-server

Analisar Servidor MCP — Análise de Intenção e Erro

Produza um relatório que responda a três perguntas sobre um servidor MCP instrumentado com o SDK de Análise MCP da Amplitude:

1. Quais ferramentas são usadas e quais falham? (volume por ferramenta + taxa de erro)
2. O que os chamadores estão tentando fazer com cada ferramenta e onde cada intenção quebra? (justificativas dentro de uma ferramenta × mensagem de erro)
3. O que a equipe deve corrigir primeiro? (correções baseadas em evidências de erro, não em intuições)

A ideia central que torna esta análise valiosa: a ferramenta localiza a correção; a justificativa explica a intenção por trás dela. Uma taxa de erro geral diz "4,5% das chamadas falham." Detalhada por ferramenta ela diz "query_chart falha 22% das vezes" — agora você sabe o que abrir. Adicionar as justificativas dentro dessa ferramenta diz "as falhas são agentes de atualização de dashboard que estão atingindo o limite de tamanho de lote" — agora você sabe o porquê, e a correção se escreve sozinha. A justificativa é em grande parte escopo da ferramenta (cada ferramenta tem seu próprio motivo para ser chamada), então a ferramenta é o eixo principal e a justificativa é o segundo corte dentro dela — agrupar justificativas globalmente apenas redescobre os limites das ferramentas enquanto mistura intenções incomparáveis.

Pré-requisitos

• Conector MCP da Amplitude ativo. Se não estiver, pare e peça ao usuário para adicionar o conector Amplitude em suas configurações de ferramentas/conector — não há fonte de dados alternativa.

• Um projeto contendo os eventos do SDK. O SDK emite eventos padrão de propriedade do SDK, todos prefixados [MCP] e — criticamente — cada propriedade padrão que eles carregam também é prefixada [MCP], eles podem ter propriedades personalizadas.

  Eventos:

  • [MCP] Tool Call Response — o carro-chefe: um evento por invocação de ferramenta que atingiu um callback de ferramenta (sucesso ou erro).
  • [MCP] Tool Call Rejected — uma tools/call que falhou antes de qualquer ferramenta ser executada (ferramenta desconhecida/desabilitada, validação de esquema de entrada). É onde pousam nomes de ferramentas alucinados/com erros de digitação, carregados em [MCP] Attempted Tool Name (mantido fora do reservado [MCP] Tool Name).
  • [MCP] Session Initialized, [MCP] Session Ended, [MCP] Tools Listed.

  Propriedades principais em [MCP] Tool Call Response: [MCP] Tool Name, [MCP] Client Name, [MCP] Client Version, [MCP] Session ID, [MCP] Auth Type, [MCP] Rationale, [MCP] Is Error, [MCP] Error Message, [MCP] Error Type (returned_error vs thrown_exception — separa uma ferramenta que relatou falha de uma que travou), [MCP] Response Duration, [MCP] Response Size, [MCP] Request Size.

• Nomes de eventos/propriedades podem variar entre versões do SDK. Nunca presuma — verifique com as ferramentas de taxonomia na Fase 0. Os nomes canônicos acima vêm do constants.ts do SDK (EVENT_PROPERTY_KEYS); se os dados do projeto discordarem, confie no projeto e adapte.

Fase 0 — Localizar e validar os dados

1. Chame a ferramenta de contexto do Amplitude (sem projectId) para listar projetos. Se houver mais de um projeto plausível e o usuário não tiver especificado, pergunte.
2. Confirme se os eventos [MCP] existem no projeto escolhido (pesquise eventos ou liste eventos; get_events filtra apenas por nome exato, então use a pesquisa para a descoberta do prefixo [MCP]).
3. Extraia as propriedades do evento para [MCP] Tool Call Response (e [MCP] Tool Call Rejected) para confirmar os nomes exatos das propriedades — lembre-se de que eles são prefixados [MCP] e em Maiúsculas (ex.: [MCP] Rationale, não tool rationale). Vincule o que você encontrar aos nomes usados nas consultas abaixo.
4. Execute uma consulta de volume/recência: totais de [MCP] Tool Call Response, [MCP] Session Initialized nos últimos 60 dias, intervalo semanal. Isso informa a janela de datas utilizável e se há dados suficientes. Abaixo de ~5k chamadas de ferramenta no total, avise o usuário que os detalhamentos por ferramenta serão escassos e as porcentagens instáveis — prossiga mesmo assim, mas mencione isso no relatório.

Registre: ID do projeto, janela de datas, volume total de chamadas. Todas as consultas posteriores usam o mesmo intervalo para que os números permaneçam comparáveis.

Fase 1 — Detalhamento por ferramenta (a espinha dorsal)

Este é o mapa principal; todo o resto se aprofunda nele.

• Volume por ferramenta: totais de [MCP] Tool Call Response, agrupados por [MCP] Tool Name, groupByLimit ~100.
• Erros por ferramenta: o mesmo, mais filtro [MCP] Is Error is "true".
• Chamadas rejeitadas por nome tentado: totais de [MCP] Tool Call Rejected agrupados por [MCP] Attempted Tool Name. Estas nunca atingem um callback, portanto são invisíveis para as duas consultas acima — mas um nome tentado de alto volume que não é uma ferramenta real é uma das descobertas mais acionáveis que existem (uma renomeação ou alucinação que os agentes continuam tentando).

Calcule por ferramenta: volume de chamadas, contagem de erros e taxa de erro, e classifique as ferramentas de duas maneiras: por volume de chamadas (o que é crítico) e por volume de erros (o que está custando mais falhas). Escolha as 3–5 principais ferramentas para análise aprofundada — favoreça alto volume de erros, não apenas alto tráfego, e honre a escolha do usuário se ele mencionou ferramentas específicas. Uma ferramenta de baixo tráfego com 90% de taxa de erro pode superar uma saudável e movimentada.

Fase 2 — Justificativas dentro de cada ferramenta principal (o "porquê")

Para cada ferramenta principal, amostre suas justificativas — totais de [MCP] Tool Call Response agrupadas por [MCP] Rationale, filtradas para aquela ferramenta ([MCP] Tool Name is "<tool>"), groupByLimit ~150. Em seguida, leia-as e agrupe-as por o que o chamador está tentando realizar com esta ferramenta, não pela redação. Orientações:

• Dentro de uma única ferramenta, você geralmente encontrará 2–5 grupos de intenção, não nove — a ferramenta já restringe o propósito. Nomeie-os por intenção (ex.: para uma ferramenta query_chart: "atualização de dashboard em tempo real", "exploração ad-hoc", "geração de relatório agendado").
• Pondere pelo volume de chamadas (cada valor de justificativa carrega seu total), não por strings distintas.
• Cuidado com um grupo de lixo: "placeholder", "ignore", "noop", "test", "dummy", letras únicas. Seu tamanho é uma descoberta de higiene de justificativa, e o lixo não deve contaminar intenções reais.
• Justificativas como "Retry after rate limit" / "Retrying X" sinalizam loops de repetição — anote-as.
• Justificativas não-inglesas são normais; agrupe-as por significado.
• Calcule a cobertura de justificativa por ferramenta (parcela das chamadas da ferramenta com uma justificativa não vazia). Se for baixa (<50%), as intenções descrevem apenas uma fatia — diga isso, e "melhorar a cobertura de justificativa no momento da instrumentação" torna-se uma recomendação em si.
• Calcule a participação da principal intenção por ferramenta (o maior grupo de intenção como % das chamadas cobertas por justificativa da ferramenta). Este é o sinal de concentração: ~90% significa que a ferramenta atende a uma tarefa e você pode otimizar fortemente para ela (apertar o esquema/descrição em torno desse caminho); uma distribuição plana (intenção principal ~30%) significa que a ferramenta está sobrecarregada e pode merecer divisão, ou seus erros serão distribuídos por intenções não relacionadas. Relate o número e, quando a intenção principal for dominante, nomeie-a ao lado da ferramenta.

Fluxos de trabalho entre ferramentas (secundário): algumas justificativas descrevem um objetivo de múltiplas ferramentas ("resolver o id do gráfico antes de atualizar o dashboard"). Onde uma única intenção claramente abrange ferramentas (ex.: search_events → create_chart → create_dashboard), destaque-a como um fluxo de trabalho na seção transversal — é a única coisa que uma visão puramente ferramenta por ferramenta perde.

Fase 3 — Análise de erro aprofundada por ferramenta

Para cada ferramenta principal, execute (filtrado para aquela ferramenta + [MCP] Is Error is "true"):

• agrupado por [MCP] Error Message → por que falha
• opcionalmente dividido por [MCP] Error Type (returned_error vs thrown_exception) quando uma mensagem é ambígua — uma falha e uma recusa bem formada ambas geram [MCP] Is Error, mas apenas uma é um bug na ferramenta.

Onde uma ferramenta tem um grupo de intenção dominante da Fase 2, qualifique os erros por justificativa (adicione o filtro contains de justificativa) para obter a frase "esta intenção quebra desta forma".

Classifique cada mensagem de erro significativa em um arquétipo — o arquétipo determina a correção:

Arquétipo	Assinatura	Padrão de correção
Nome de ferramenta desatualizado/alucinado	[MCP] Tool Call Rejected com [MCP] Attempted Tool Name = um nome renomeado ou com som plausível	Apelidos no lado do servidor para ferramentas renomeadas; respostas de rejeição que nomeiam a ferramenta real mais próxima para que os agentes se autocorrijam de uma só vez
Parâmetro obrigatório ausente	erro de validação, "Required", nome do caminho indica um parâmetro	Afrouxe o esquema (aceite valor único ou array, adicione padrões) ou faça a descrição da ferramenta declarar os requisitos para que os agentes acertem antes da execução
Incompatibilidade de formato de esquema	"Expected object, received string" etc.	Adicione coerção no lado do servidor ou um exemplo embutido na descrição da ferramenta
Colisão de limite rígido	"Maximum of N …", "too_big"	Aumente o limite, divida em blocos automaticamente no servidor ou declare o limite na descrição do parâmetro — os agentes atualmente só aprendem limites falhando
Violação de intervalo/retenção	"time range too large", "does not retain data before …"	Coerção automática (ex.: reduzir granularidade) em vez de gerar erro; anuncie os limites de retenção/intervalo na carga de contexto
Parâmetro circular	uma ferramenta de contexto/descoberta exige o próprio ID que ela existe para fornecer	Faça as ferramentas de descoberta funcionarem com zero argumentos obrigatórios, usando o padrão do token de autenticação
Permissão negada	linguagem de função/permissão	Classe de erro distinta para que "não permitido" seja separável de "quebrado"; geralmente também uma lacuna de documentação/onboarding
Erro agendado recorrente	mesma mensagem repetindo diariamente na mesma ferramenta	Corrija o chamador do job se for interno; para o produto, sinalize como automação degradando silenciosamente — ninguém está monitorando uma janela de chat
Transitório/upstream	5xx, timeouts, limites de taxa	Dicas de repetição após no corpo do erro; verifique se as repetições realmente ocorrem (veja o funil de loops)

As melhores mensagens de erro indicam a correção ("re-execute com start >= …"). Avalie toda mensagem de erro de alto volume com esse padrão — "tornar este erro tão acionável quanto o seu melhor" é frequentemente uma recomendação legítima.

Fase 4 — Métricas de contexto opcionais

Adicione se o tempo permitir; elas afiam a história:

• Loop de erro repetido: funil de 3 etapas, cada etapa [MCP] Tool Call Response com [MCP] Is Error is "true", mantendo [MCP] Tool Name constante, janela de conversão ~1h. Mostra qual parcela de usuários com erro entra em loops na mesma ferramenta. (As etapas não precisam ser eventos consecutivos — diga "3+ erros na mesma ferramenta dentro de uma hora", não "3 consecutivos".)
• Erro → recuperação: funil de 2 etapas, erro seguido de sucesso, mantendo o nome da ferramenta constante. Alta recuperação + alta taxa de loop juntos significam que o custo são tokens/latência desperdiçados, não abandono — uma conclusão materialmente diferente.
• Mistura de clientes: únicos agrupados por [MCP] Client Name. Grande parcela "desconhecido" ou nomes de cliente quase duplicados (maiúsculas/minúsculas, variantes prefixadas por plugin) são descobertas de instrumentação que vale a pena relatar.

Fase 5 — Verificar, depois escrever

Antes de escrever, verifique novamente pelo menos um número principal de uma segunda maneira (ex.: taxa de erro geral via uma consulta separada de totais de dois eventos). Recalcule cada porcentagem que você citar a partir de totais brutos. Se um número não puder ser verificado, corte-o ou rotule-o como estimativa.

Estrutura do relatório

Use este modelo — organizado primeiro por ferramenta:

# Análise do Servidor MCP — <nome do servidor/projeto>

Dados: <projeto>, <janela de datas>, <N> chamadas de ferramenta, taxa de erro geral <X>%.
Nota de método: os detalhamentos por ferramenta são resultados exatos de consultas; as intenções dentro das ferramentas são derivadas
pelo modelo a partir de justificativas (direcionais). Nomes de chamadas rejeitadas vêm de [MCP] Tool Call Rejected.

## Ferramentas em resumo
<tabela: ferramenta | chamadas | erros | taxa de erro | principal intenção (% parcela) | cobertura de justificativa>
<uma linha sobre nomes de ferramentas rejeitados/tentados se material; destaque justificativas de lixo se material>

## Análise aprofundada: 3–5 principais ferramentas (classificadas por volume de erros)
Para cada ferramenta:
**Ferramenta: <nome> — <chamadas>, <taxa de erro> — para que serve: <uma frase>**
- Intenções (justificativas dentro desta ferramenta): <grupo: parcela>, …
- 1–4 recomendações numeradas. Cada uma declara a evidência (mensagem de erro + contagem),
  o arquétipo e a correção concreta. Comece com a correção que remove o maior volume de erros.

## Descobertas transversais
<fluxos de trabalho entre ferramentas, taxas de loop/recuperação, higiene de nomes de cliente, higiene de justificativa, tráfego de teste interno, …>

## A conclusão em uma frase
<a única alteração que remove o maior volume de falhas, com seu número>

Estilo: números ao lado de cada afirmação; nomeie as mensagens de erro textualmente (truncadas) para que engenheiros possam pesquisá-las; recomendações formuladas como ações ("Criar apelido para query_chart → query_charts"), não como observações ("a nomeação de ferramentas poderia ser melhorada").

Gráficos na saída

Renderize gráficos de suporte do Amplitude onde o cliente suportar, usando as ferramentas de consulta e renderização de gráficos ad-hoc (construa uma definição eventsSegmentation/funnels, depois renderize-a). Seja deliberado sobre o que pode e o que não pode ser um gráfico:

• Passível de gráfico — qualquer coisa baseada em consulta. Estes são resultados reais de segmentação/funil do Amplitude, então renderize-os: chamadas e erros por ferramenta (agrupados por [MCP] Tool Name), taxa de erro ao longo do tempo, chamadas rejeitadas por [MCP] Attempted Tool Name, os funis de loop de erro repetido e recuperação por ferramenta, e mistura de clientes por [MCP] Client Name. O detalhamento por ferramenta é o gráfico principal natural.
• Não passível de gráfico — os grupos de intenção dentro das ferramentas. O agrupamento de justificativas em intenções acontece neste modelo; esses agrupamentos não existem como uma propriedade do Amplitude, portanto não há gráfico salvo para "chamadas por intenção." Apresente as intenções como uma tabela construída a partir dos totais de justificativas e diga claramente que os números de intenção são derivados do modelo (direcionais) enquanto os gráficos que você renderiza são resultados exatos de consultas. Não insinue que um gráfico renderizado dá suporte ao agrupamento de intenções.

Livro de Receitas de Consultas

Todas as consultas são definições eventsSegmentation ou funnels contra o ID do projeto da Fase 0. Ajuste os nomes de eventos/propriedades para o que a Fase 0 verificou. Formas conhecidas por funcionar:

Detalhamento de ferramentas (Fase 1):

{"type":"eventsSegmentation","app":"<PROJECT_ID>","name":"[MCP] Chamadas por Ferramenta",
 "params":{"range":"Últimos 30 Dias",
  "events":[{"event_type":"[MCP] Tool Call Response",
    "group_by":[{"type":"event","value":"[MCP] Tool Name"}]}],
  "metric":"totals","countGroup":"User","groupBy":[],"int

... [truncado para tradução]