Referência de ferramentas do MCP

O AppSignal MCP expõe 24 ferramentas em sete áreas: incidentes de erro, performance, detecção de anomalias, logging, métricas, dashboards e descoberta de apps. As ferramentas incluem operações de leitura e escrita.

​

Workflows

Estes exemplos mostram como as ferramentas se combinam para tarefas comuns.

​

Investigando um erro de produção

1. Liste as exceções abertas recentes: “Show me all open incidents in production from the last 24 hours”
2. Obtenha detalhes completos sobre um incidente específico: “Get the details for incident #847 including the stack trace”
3. Puxe traces para ver o que aconteceu no nível do código: “Get the error traces for incident #847”
4. Documente seus achados: “Add a note to incident #847: investigated the database timeout — connection pool was exhausted during peak traffic”
5. Resolva-o: “Close incident #847”

​

Analisando uma action lenta

1. Obtenha uma visão geral de performance: “Which actions are slowest in the web namespace right now?”
2. Puxe traces para o pior caso: “Get traces for BlogPostsController#index from the last hour”
3. Inspecione a árvore de spans para encontrar o gargalo: “Show me the full span tree for trace abc123”
4. Investigue um span específico: “Get the details for span def456 in trace abc123”

​

Fazendo triagem de um lote de incidentes

1. “Find all open incidents in the background namespace from the last week”
2. “Mark incidents #120, #121, and #122 as work in progress and assign them to Jana”
3. “Close all incidents related to ActionMailer — they were fixed in the last deploy”

​

Pesquisando logs durante um incidente

1. “Find all error logs from the last hour”
2. “Show me logs where message contains ‘timeout’ on web-1 between 14:00 and 15:00”
3. “Get fatal logs from the payments source over the last 30 minutes”

​

Reconstruindo a jornada de um cliente

Quando um usuário reporta que algo deu errado, a resposta geralmente está espalhada por logs de várias fontes, além de erros e traces. Costurar essa linha do tempo à mão é o tipo de trabalho que a UI de logging não pode fazer por você, mas um agente pode.

1. “Get all logs for user.id=4321 from production over the last 24 hours, across every source”
2. “Narrow that to the window between 14:00 and 15:30 UTC and group the results by source”
3. “List any open exception incidents from production in that same window — anything tagged with user.id=4321?”
4. “For incident #903, pull the error traces and walk the span tree”
5. “Summarize what happened: which actions did this user hit, what failed, and where did the error originate?”

Isso usa get_log_lines, get_exception_incidents e get_traces em uma única conversa. A etapa final de resumo é onde o MCP entrega valor — o agente compõe a narrativa, e não você.

​

Configurando processamento de logs

O AppSignal executa ações em linhas de log durante a ingestão, na ordem que você definir. Um padrão comum é emitir uma métrica, criar um gatilho e depois filtrar — isso garante que o AppSignal capture o sinal antes de descartar a linha de log.

1. Verifique as ações de log line existentes e sua ordem: use get_app_resources com sections: ["log_line_actions"]
2. “Create a metrics action that counts log lines where severity is error as log.error_count”
3. “Add a trigger action that fires an alert when severity is fatal”
4. “Add a filter to drop all health check log lines”
5. “Reorder those actions so the metrics action runs first, then the trigger, then the filter”

​

Criando um gatilho de detecção de anomalias

1. Descubra as métricas disponíveis: “What metrics are available for my production app?”
2. Verifique as tags disponíveis: “What tags are available for response_time?”
3. Crie o gatilho: “Create a trigger that fires when mean response time exceeds 500ms for more than 5 minutes, and notify the Slack #alerts channel”
4. Arquive um gatilho antigo depois de substituído: use get_triggers para encontrar o ID primeiro, depois “Archive the old response_time trigger”

​

Construindo um dashboard de monitoramento

1. “What metrics are available for my production app?”
2. “Create a dashboard called ‘API Health’ in production”
3. “Add a line chart of p95 response time by action to the API Health dashboard”
4. “Add an area chart of error rate broken down by namespace”

---

​

Referência de ferramentas

Toda ferramenta recebe app_name e app_environment para identificar a aplicação alvo. Ambos são comparados sem diferenciar maiúsculas de minúsculas, então MyApp/Production e myapp/production resolvem para a mesma aplicação.

​

Descoberta de apps

​

get_applications

Obtenha todas as aplicações do AppSignal às quais o usuário tem acesso. Retorna as aplicações no formato app_name/app_environment. Use isto primeiro para descobrir as aplicações disponíveis antes de chamar outras ferramentas. Nenhum parâmetro é necessário.

---

​

get_app_resources

Descubra os recursos disponíveis em uma aplicação do AppSignal — namespaces, dashboards, usuários, notificadores, fontes de log, ações de log line e marcadores de deploy. Particularmente útil ao configurar gatilhos, atribuir incidentes ou entender a estrutura de uma aplicação.

---

​

Incidentes de erro

​

get_exception_incidents

Liste e pesquise exceções e erros do AppSignal. Use isto para obter uma visão geral de exceções recentes, pesquisar em um período de tempo, encontrar incidentes por estado, ou verificar quais incidentes precisam de atenção. Retorna 50 incidentes por página.

---

​

get_incident

Obtenha informações detalhadas sobre um incidente do AppSignal. Retorna o estado atual, atribuição, primeira e última ocorrência, mensagens de erro, stack traces ou detalhes de alerta de anomalia. Suporta incidentes de exceção e anomalia.

---

​

update_incidents

Atualize incidentes em massa para uma aplicação do AppSignal. Use isto para alterar o estado do incidente, atualizar a severidade ou atribuir e desatribuir membros da equipe em vários incidentes de uma vez. Use get_app_resources com sections: ["users"] para encontrar IDs de usuários para atribuição.

---

​

create_incident_note

Crie uma nota em um incidente do AppSignal. Markdown é suportado. Use isto para adicionar comentários, atualizações de status, descobertas de investigação ou passos de resolução.

---

​

Performance

​

get_performance

Visão geral de performance: incidentes de performance baseados em amostras e actions lentas a partir de traces. Para apps padrão de Ruby e Elixir, retorna incidentes de performance baseados em amostras. Para apps que também enviam traces do OpenTelemetry, retorna adicionalmente uma lista ranqueada de actions com duração média, throughput e taxa de erro. Apps em migração para OpenTelemetry podem retornar ambos. Ferramentas de acompanhamento: use get_incident para inspecionar um incidente de performance específico, get_traces para puxar traces de amostra para uma action lenta, e update_incidents para alterar estado, severidade ou responsáveis.

---

​

get_traces

Consulte traces de performance e erro, inspecione árvores de spans e visualize detalhes de spans. Suporta dois tipos de trace:

• Performance traces — identificados por namespace e action_name. Use-os para investigar requisições lentas.
• Error traces — identificados por digest. Obtenha o digest a partir de get_incident ou get_exception_incidents, depois use-o aqui para ver os traces de erro reais.

Cada tipo de trace suporta três modos:

1. Modo de lista — encontre traces e obtenha IDs de trace. Forneça namespace + action_name, ou digest.
2. Modo de árvore — passe um trace_id para ver todos os spans como uma árvore compacta.
3. Modo de detalhe de span — passe trace_id e span_id para obter atributos completos do span, eventos e informações de recurso.

O fluxo típico é: listar traces → inspecionar uma árvore de trace → investigar um span.

---

​

Detecção de anomalias

​

get_anomaly_incidents

Liste e pesquise alertas de detecção de anomalias do AppSignal. Retorna 50 alertas por página, incluindo timestamps e valores para cada alerta.

---

​

get_triggers

Liste gatilhos de detecção de anomalias para uma aplicação do AppSignal. Retorna gatilhos ativos (não arquivados) com sua configuração completa — condições, notificadores e links de dashboard. Use isto para encontrar IDs de gatilhos antes de chamar manage_trigger ou archive_trigger.

---

​

manage_trigger

Crie ou atualize um gatilho de detecção de anomalias. Os gatilhos são imutáveis. Quando você atualiza um gatilho, o AppSignal arquiva o existente (fechando todos os seus alertas e incidentes) e cria um novo com uma referência de cadeia de versão. Forneça todos os campos tanto para operações de criação quanto de atualização. Use get_metric_names e get_metric_tags para descobrir métricas e campos disponíveis. Use get_app_resources(sections: ["notifiers"]) para encontrar IDs de notificadores.

---

​

archive_trigger

Arquive um gatilho de detecção de anomalias e feche todos os alertas e incidentes associados. Idempotente — não faz nada se o gatilho já estiver arquivado. Use get_triggers para encontrar o ID do gatilho.

---

​

Logging

​

get_log_lines

Consulte linhas de log usando a sintaxe de expressão do AppSignal. Suporta correspondência exata, contém, negação, comparações numéricas, lógica booleana e atributos aninhados. Retorna até 100 linhas por chamada, mais recentes primeiro por padrão. Para intervalos de tempo grandes, divida em várias chamadas e itere para frente. Sintaxe de consulta: Campos disponíveis: severity, hostname, group, message, e quaisquer atributos personalizados.

---

​

manage_log_line_action

Crie ou atualize uma ação de log line. As ações de log line são executadas durante a ingestão de logs, na ordem que você definir. Existem três tipos:

• filter — descarta as linhas de log correspondentes para que nunca sejam armazenadas ou processadas posteriormente
• trigger — dispara alertas e incidentes quando a query corresponde
• metrics — extrai métricas de counter, gauge ou distribution das linhas de log correspondentes

A ordem de execução importa: se um filtro descartar uma linha de log, as ações subsequentes nunca a verão. Um padrão comum é colocar ações de métrica e gatilho antes de qualquer ação de filtro. Use reorder_log_line_actions para alterar a ordem após a criação. Novas ações são adicionadas no final da ordem de execução.

---

​

reorder_log_line_actions

Altere a ordem de execução das ações de log line. Forneça IDs de ação na sequência desejada. Quaisquer IDs de ação não incluídos são adicionados no final em sua ordem relativa atual. Use get_app_resources(sections: ["log_line_actions"]) para encontrar os IDs e ver a ordem atual.

---

​

delete_log_line_action

Exclua permanentemente uma ação de log line. Use get_app_resources(sections: ["log_line_actions"]) para encontrar o ID da ação primeiro.

---

​

Métricas

​

discover_metrics

Descubra categorias de métricas disponíveis e suas métricas para monitoramento. Use isto para obter uma visão geral do que pode monitorar, ou para investigar uma categoria específica. Também aceita uma referência dashboard:id para mostrar métricas usadas em um dashboard específico.

---

​

get_metric_names

Obtenha os nomes de todas as métricas para a aplicação fornecida. Retorna os nomes das métricas como uma string separada por vírgulas. Use-os como entrada para get_metric_tags, get_metrics_timeseries e get_metrics_list.

---

​

get_metric_tags

Obtenha as tags e o tipo de métrica (Gauge, Counter, etc.) para uma métrica específica. Use os resultados para construir queries válidas com get_metrics_timeseries e get_metrics_list.

---

​

get_metrics_timeseries

Obtenha uma timeseries para uma métrica na aplicação fornecida. Retorna dados ponto a ponto para um determinado intervalo de tempo, tipo de métrica e combinação de tags. Os valores de tag suportam correspondência por wildcard com *.

---

​

get_metrics_list

Obtenha um valor agregado para uma métrica em um intervalo de tempo. Retorna um único valor agregado em vez de uma timeseries ponto a ponto. Útil para visões de resumo.

---

​

Dashboards

​

manage_dashboard

Crie ou atualize um dashboard do AppSignal. Esta ferramenta gerencia apenas os metadados do dashboard (título e descrição). Use create_dashboard_visual e update_dashboard_visual para adicionar gráficos.

---

​

create_dashboard_visual

Adicione um novo gráfico ou visualização a um dashboard existente. Use discover_metrics ou get_metrics_list para encontrar métricas disponíveis primeiro.

---

​

update_dashboard_visual

Atualize um gráfico ou visualização existente em um dashboard. Todos os campos são opcionais, exceto os identificadores. Campos não especificados mantêm seus valores atuais. Se metrics for fornecido, ele substitui todas as métricas existentes naquele visual.

---

​

Permissões de token

Cada token MCP tem permissões configuráveis por conjunto de ferramentas: app, exceptions, performance, metrics, anomalies, dashboards, logging. Cada conjunto de ferramentas pode ser definido como read, write ou desabilitado. Os tokens também podem ser escopados para aplicações específicas e configurados para expor automaticamente novas ferramentas conforme elas são adicionadas. Para gerar um token:

1. Selecione o ícone do seu perfil.
2. Vá para Account Settings.
3. Selecione MCP Tokens para criar um novo token.

---

​

Faltando uma ferramenta?