Scout Monitoring MCP

Scout Monitoring MCP

Este repositório contém o código para executar localmente um servidor MCP que pode acessar dados do Scout Monitoring por meio da API do Scout. Fornecemos uma imagem Docker que pode ser baixada e executada pelo seu Assistente de IA para acessar os dados do Scout Monitoring.

Isso coloca os dados de desempenho e erros do Scout Monitoring diretamente nas mãos do seu Assistente de IA. Para Rails, Django, FastAPI, Laravel e muito mais. Use-o para obter traces e erros com informações de linha de código que a IA pode usar para direcionar correções diretamente no seu editor e base de código. Consultas N+1, endpoints lentos, consultas lentas, consumo excessivo de memória, problemas de throughput - todos os seus problemas de desempenho favoritos surgem e são explicados exatamente onde você está trabalhando.

Se isso tornar sua vida um pouquinho melhor, por que não dar uma :star:?!

Assistente de Configuração

A maneira mais simples de configurar e começar a usar o Scout MCP é com nosso assistente de configuração interativo. Ele cuida de todos os pré-requisitos e etapas de instalação para você.

Execute via npx:

npx @scout_apm/wizard

Compile e execute a partir do código-fonte:

cd ./wizard
npm install
npm run build
node dist/wizard.js

O assistente guiará você por:

• Seleção da sua plataforma de codificação com IA (Cursor, Claude Code, Claude Desktop)
• Inserção da sua chave de API do Scout
• Configuração automática das definições do servidor MCP

Plataformas Suportadas

O assistente atualmente oferece suporte à configuração para:

• Cursor - Configura automaticamente as definições do MCP
• Claude Code (CLI) - Fornece o comando correto a ser executado
• Claude Desktop - Atualiza o arquivo de configuração para Windows/Mac

Para todas as outras, ele exibirá um JSON que você pode copiar/colar na configuração MCP do seu Assistente de IA.

Pré-requisitos

O Assistente é uma ótima maneira de começar, mas você também pode configurar tudo manualmente. Você precisará ter ou criar uma conta no Scout Monitoring e obter uma chave de API.

1. https://scoutapm.com/users/sign_up?utm_source=github&utm_medium=github&utm_campaign=scout-mcp-local
2. Instale o Scout Agent na sua aplicação e envie dados para o Scout!
   • Ruby
   • Python
   • PHP
   • Se você estiver testando localmente, certifique-se de que monitor: true, errors_enabled: true estejam definidos na sua configuração para a melhor experiência
3. Acesse configurações para obter ou criar uma chave de API
   • Esta não é a sua "Agent Key"; é a "API Key" que pode ser criada na página de Configurações
   • Esta é uma chave somente leitura que só pode acessar dados na sua conta
4. Instale o Docker. As instruções abaixo pressupõem que você pode iniciar um contêiner Docker

O servidor MCP atualmente não iniciará sem uma chave de API definida, seja no ambiente ou por um argumento de linha de comando na inicialização.

Instalação

Recomendamos usar a imagem Docker fornecida para executar o servidor MCP. Ela deve ser iniciada pelo seu Assistente de IA e configurada com sua chave de API do Scout. Muitos clientes locais permitem especificar um comando para executar o servidor MCP em algum local. Alguns exemplos são fornecidos abaixo.

A imagem Docker está disponível no Docker Hub.

É claro que você sempre pode clonar este repositório e executar o servidor MCP diretamente; uv ou outras ferramentas de gerenciamento de ambiente são recomendadas.

Configurar um Cliente local (ex.: Claude/Cursor/VS Code Copilot)

Se você quiser configurar o MCP manualmente, isso geralmente significa apenas fornecer um comando para executar o servidor MCP com sua chave de API no ambiente na configuração do seu Assistente de IA. Aqui está o formato do JSON (a chave de nível superior varia):

{
  "mcpServers": {
    "scout-apm": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "--env", "SCOUT_API_KEY", "scoutapp/scout-mcp-local"],
      "env": { "SCOUT_API_KEY": "your_scout_api_key_here"}
    }
  }
}

claude mcp add scoutmcp -e SCOUT_API_KEY=your_scout_api_key_here -- docker run --rm -i -e SCOUT_API_KEY scoutapp/scout-mcp-local

{
  "mcpServers": {
    "scout-apm": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "--env", "SCOUT_API_KEY", "scoutapp/scout-mcp-local"],
      "env": { "SCOUT_API_KEY": "your_scout_api_key_here"}
    }
  }
}

Usando o Scout Monitoring MCP

O MCP do Scout tem como objetivo colocar dados de erros e desempenho diretamente nas... mãos? do seu Assistente de IA. Use-o para obter traces e erros com informações de linha de código que a IA pode usar para direcionar correções diretamente no seu editor.

A maioria dos assistentes mostrará tanto as chamadas brutas de ferramentas quanto realizará análises. Assistentes de desktop podem prontamente criar aplicações JS personalizadas para explorar quaisquer dados que você desejar. Assistentes integrados a editores de código podem usar dados de trace e backtraces de erros para fazer correções diretamente na sua base de código.

Combine o MCP do Scout com as outras ferramentas do seu Assistente de IA para:

• Criar issues ricas no GitHub/GitLab com base em dados de erros e desempenho
• Tornar o JIRA divertido - faça seu Assistente de IA criar tickets com todos os detalhes
• Gerar PRs que corrigem erros e problemas de desempenho específicos

Ferramentas

O Scout MCP fornece as seguintes ferramentas para acessar dados do Scout APM:

• list_apps - Lista as aplicações Scout APM disponíveis, com filtragem opcional por data de última atividade
• get_app_metrics - Obtém dados de uma métrica individual (response_time, throughput, etc.) para uma aplicação específica
• get_app_endpoints - Obtém todos os endpoints de uma aplicação com métricas de desempenho agregadas
• get_endpoint_metrics - Obtém métricas de séries temporais para um endpoint específico em uma aplicação
• get_app_endpoint_traces - Obtém traces recentes de uma aplicação filtrados para um endpoint específico
• get_app_trace - Obtém um trace individual com todos os spans e informações detalhadas de execução
• get_app_error_groups - Obtém grupos de erros recentes de uma aplicação, opcionalmente filtrados por endpoint
• get_app_insights - Obtém insights de desempenho, incluindo consultas N+1, consumo excessivo de memória e consultas lentas

Recursos

O Scout MCP fornece modelos de configuração como recursos que seu assistente de IA pode ler e aplicar:

• scoutapm://config-resources/{framework} - Instruções de configuração para o framework ou biblioteca suportado (rails, django, flask, fastapi)
• scoutapm://config-resources/list - Lista todos os modelos de configuração disponíveis
• scoutapm://metrics - Lista de todas as métricas disponíveis para o Scout APM

Prompts Úteis

Configuração e Instalação

• "Me ajude a configurar o monitoramento do Scout para minha aplicação Rails"
• "Crie um arquivo de configuração do Scout APM para meu projeto Django com a chave ABC123"

Desempenho e Monitoramento

• "Resuma as ferramentas disponíveis no Scout Monitoring MCP."
• "Encontre os endpoints mais lentos da aplicação my-app-name nos últimos 7 dias. Gere uma tabela com os resultados incluindo o tempo médio de resposta, throughput e tempo de resposta P95."
• "Mostre-me os erros de maior frequência da aplicação Foo nas últimas 24 horas. Obtenha o detalhe do erro mais recente, examine o backtrace e sugira uma correção."
• "Obtenha quaisquer insights recentes de n+1 para a aplicação Bar. Extraia o trace específico por id e me ajude a otimizá-lo com base nos dados do backtrace."

Uso de Tokens

Atualmente estamos mais interessados em expandir as informações disponíveis do que em controlar estritamente o tamanho das respostas das nossas ferramentas MCP. Se o seu Assistente de IA tiver um limite de tokens configurável (ex.: Claude Code export MAX_MCP_OUTPUT_TOKENS=50000), recomendamos defini-lo generosamente alto, ex.: 50.000 tokens.

Desenvolvimento Local

Usamos uv e taskipy para gerenciar ambientes e executar tarefas deste projeto.

Executar com o Inspector

uv run task dev

Conecte-se no inspector para adicionar a chave de API, definida para o transporte STDIO

Compilar a imagem Docker

docker build -t scout-mcp-local .

Release

1. Crie um branch e incremente as versões com uv run python bump_versions.py
2. Faça o merge
3. Crie um release no GitHub com a nova versão (gh release create v2025.11.3 --generate-notes --draft)

Publicar o release envia a tag v*, e o CI publica a imagem Docker, o pacote PyPI e, em seguida, as entradas no MCP Registry:

• server.json → com.scoutapm/scout-mcp-local (este servidor; sua versão é incrementada por bump_versions.py)
• server.remote.json → com.scoutapm/scout-monitoring (o servidor hospedado em https://scoutapm.com/mcp). Incremente seu version manualmente quando alterar seus metadados; versões inalteradas são ignoradas.

Chave do MCP Registry

O registry verifica que somos proprietários do namespace com.scoutapm/* por meio de um registro DNS TXT no apex de scoutapm.com contendo uma chave pública Ed25519. O CI faz login com a chave privada correspondente do segredo do repositório MCP_REGISTRY_PRIVATE_KEY. Para rotacioná-la:

openssl genpkey -algorithm Ed25519 -out key.pem
# Public key for the TXT record: replace the existing v=MCPv1 record, don't add a second one
echo "v=MCPv1; k=ed25519; p=$(openssl pkey -in key.pem -pubout -outform DER | tail -c 32 | base64)"
# Private key (hex) for the MCP_REGISTRY_PRIVATE_KEY secret
openssl pkey -in key.pem -noout -text | grep -A3 "priv:" | tail -n +2 | tr -d ' :\n'

Para os bots:

mcp-name: com.scoutapm/scout-mcp-local