Sentry MCP

sentry-mcp

O serviço MCP do Sentry foi projetado principalmente para agentes de codificação com supervisão humana. Nossa seleção de ferramentas e prioridades estão focadas em fluxos de trabalho de desenvolvimento e casos de uso de depuração, em vez de fornecer um servidor MCP de propósito geral para todas as funcionalidades do Sentry.

Este servidor MCP remoto atua como middleware para a API upstream do Sentry, otimizado para assistentes de codificação como Cursor, Claude Code e ferramentas de desenvolvimento similares. Ele é baseado no trabalho da Cloudflare em direção a MCPs remotos.

Primeiros Passos

Você encontrará tudo o que precisa saber visitando o serviço implantado em produção:

https://mcp.sentry.dev

Se você deseja contribuir, aprender como funciona ou executar isso para um Sentry auto-hospedado, continue abaixo.

Plugin do Claude Code

Instale como um plugin do Claude Code para delegação automática de subagentes:

claude plugin marketplace add getsentry/sentry-mcp
claude plugin install sentry-mcp@sentry-mcp

Isso fornece um subagente sentry-mcp para o qual o Claude delega automaticamente quando você pergunta sobre erros, problemas, traces ou desempenho do Sentry.

Para variantes de ferramentas e recursos voltados para o futuro:

claude plugin install sentry-mcp@sentry-mcp-experimental

Stdio vs Remoto

Embora este repositório seja focado em atuar como um serviço MCP, também oferecemos suporte a um transporte stdio. Isso ainda é um trabalho em andamento, mas é a maneira mais fácil de adaptar e executar o MCP em uma instalação auto-hospedada do Sentry.

Nota: As ferramentas de busca com IA (search_events, search_issues, etc.) exigem um provedor de LLM (OpenAI, Azure OpenAI, Anthropic ou OpenRouter). Essas ferramentas usam processamento de linguagem natural para traduzir consultas para a sintaxe de consulta do Sentry. Sem um provedor configurado, essas ferramentas específicas estarão indisponíveis, mas todas as outras ferramentas funcionarão normalmente.

Para utilizar o transporte stdio, você precisará criar um Token de Autenticação de Usuário no Sentry com os escopos necessários. No momento em que este texto foi escrito, isso é:

org:read
project:read
project:write
team:read
team:write
event:write

Inicie o transporte:

npx @sentry/mcp-server@latest --access-token=sentry-user-token

Precisa se conectar a uma implantação auto-hospedada? Adicione --host (apenas o nome do host, por exemplo, --host=sentry.example.com) ao executar o comando. Para implantações internas isoladas que expõem apenas HTTP simples, adicione também --insecure-http.

Alguns recursos (como o Seer) podem não estar disponíveis em instâncias auto-hospedadas. Você pode desabilitar habilidades específicas para evitar que ferramentas não suportadas sejam expostas:

npx @sentry/mcp-server@latest --access-token=TOKEN --host=sentry.example.com --disable-skills=seer

Para instâncias auto-hospedadas sem TLS:

npx @sentry/mcp-server@latest --access-token=TOKEN --host=sentry.internal:9000 --insecure-http

Remoto com um Token Explícito do Sentry

Clientes remotos que suportam cabeçalhos HTTP personalizados podem passar um token de API upstream do Sentry diretamente para o transporte da Cloudflare:

{
  "mcpServers": {
    "sentry": {
      "url": "https://mcp.sentry.dev/mcp",
      "headers": {
        "Authorization": "Sentry-Bearer ${SENTRY_ACCESS_TOKEN}"
      }
    }
  }
}

Sentry-Bearer é intencionalmente separado de Bearer: Bearer é reservado para tokens de acesso OAuth do MCP. Com Sentry-Bearer, o worker não armazena, valida, troca ou atualiza o token upstream. Ele encaminha o token através das mesmas chamadas de API do Sentry usadas por sessões com suporte OAuth, e o cliente ou provedor upstream permanece responsável pelo tempo de vida e atualização do token.

A autenticação remota direta usa como padrão todas as habilidades MCP ativas. Você pode restringir as ferramentas expostas com ?skills=inspect,triage ou ?disable-skills=seer.

Variáveis de Ambiente

SENTRY_ACCESS_TOKEN=         # Required: Your Sentry auth token

# LLM Provider Configuration (required for AI-powered search tools)
EMBEDDED_AGENT_PROVIDER=     # Required when multiple provider keys are set: 'openai', 'azure-openai', 'anthropic', or 'openrouter'
OPENAI_API_KEY=              # Required if using OpenAI
ANTHROPIC_API_KEY=           # Required if using Anthropic
OPENROUTER_API_KEY=          # Required if using OpenRouter
OPENROUTER_MODEL=            # Optional OpenRouter model, defaults to 'openai/gpt-5'

# Optional overrides
SENTRY_HOST=                 # For self-hosted deployments
MCP_DISABLE_SKILLS=          # Disable specific skills (comma-separated, e.g. 'seer')

Importante: Sempre defina EMBEDDED_AGENT_PROVIDER para especificar explicitamente seu provedor de LLM. A detecção automática baseada apenas em chaves de API está obsoleta e será removida em uma versão futura. Consulte docs/operations/embedded-agents.md para opções de configuração detalhadas.

Exemplo de Configuração MCP

{
  "mcpServers": {
    "sentry": {
      "command": "npx",
      "args": ["@sentry/mcp-server"],
      "env": {
        "SENTRY_ACCESS_TOKEN": "your-token",
        "EMBEDDED_AGENT_PROVIDER": "openai",
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}

Se você deixar a variável de host não definida, a CLI automaticamente direciona para o serviço SaaS do Sentry. Defina a substituição apenas quando operar o Sentry auto-hospedado.

Para instâncias auto-hospedadas que não suportam o Seer:

{
  "mcpServers": {
    "sentry": {
      "command": "npx",
      "args": ["@sentry/mcp-server"],
      "env": {
        "SENTRY_ACCESS_TOKEN": "your-token",
        "SENTRY_HOST": "sentry.example.com",
        "MCP_DISABLE_SKILLS": "seer"
      }
    }
  }
}

MCP Inspector

O MCP inclui um Inspector, para testar facilmente o serviço:

pnpm inspector

Insira a URL do servidor MCP (http://localhost:5173) e clique em conectar. Isso deve acionar o fluxo de autenticação para você.

Nota: Se você tiver problemas com seu fluxo OAuth ao acessar o inspector em 127.0.0.1, tente usar localhost visitando http://localhost:6274.

Desenvolvimento Local

Para contribuir com alterações, você precisará configurar seu ambiente local:

1. Configure o ambiente e as habilidades do agente:

   make setup-env  # Creates .env files and installs shared agent skills
   

   Isso também executa npx @sentry/dotagents install para instalar habilidades compartilhadas de getsentry/skills em .agents/skills/ (link simbólico em .claude/skills e .cursor/skills). Se você precisar atualizar as habilidades mais tarde, execute-o diretamente:

   npx @sentry/dotagents install
   

2. Crie um Aplicativo OAuth no Sentry (Configurações => API => Aplicativos):

   • URL da Página Inicial: http://localhost:5173
   • URIs de Redirecionamento Autorizados: http://localhost:5173/oauth/callback
   • Anote seu ID do Cliente e gere um segredo do Cliente

3. Configure suas credenciais:

   • Edite .env no diretório raiz e adicione OPENAI_API_KEY ou OPENROUTER_API_KEY
   • Edite packages/mcp-cloudflare/.env e adicione:
     • SENTRY_CLIENT_ID=your_development_sentry_client_id
     • SENTRY_CLIENT_SECRET=your_development_sentry_client_secret
     • COOKIE_SECRET=my-super-secret-cookie

4. Inicie o servidor de desenvolvimento:

   pnpm dev
   

Verificar

Execute o servidor localmente para disponibilizá-lo em http://localhost:5173

pnpm dev

Para testar o servidor local, insira http://localhost:5173/mcp no Inspector e clique em conectar. Depois de seguir as instruções, você poderá "Listar Ferramentas".

Testes

Existem três suítes de teste incluídas: testes unitários, avaliações e testes manuais.

Testes unitários podem ser executados usando:

pnpm test

Avaliações exigem um arquivo .env na raiz do projeto com alguma configuração:

# .env (in project root)
OPENAI_API_KEY=      # Use OpenAI-backed AI-powered tools
OPENROUTER_API_KEY=  # Or use OpenRouter-backed AI-powered tools

Nota: O arquivo .env raiz fornece padrões para todos os pacotes. Pacotes individuais podem ter seus próprios arquivos .env para substituir esses padrões durante o desenvolvimento.

Feito isso, você pode executá-los usando:

pnpm eval

Testes manuais (preferidos para testar alterações no MCP):

# Test with local dev server (default: http://localhost:5173)
pnpm -w run cli "who am I?"

# Test agent mode (use_sentry tool only)
pnpm -w run cli --agent "who am I?"

# Test against production
pnpm -w run cli --mcp-host=https://mcp.sentry.dev "query"

# Test with local stdio mode (requires SENTRY_ACCESS_TOKEN)
pnpm -w run cli --access-token=TOKEN "query"

Nota: A CLI usa como padrão http://localhost:5173. Substitua com --mcp-host ou defina a variável de ambiente MCP_URL.

Guias de teste abrangentes:

• Teste Stdio: Consulte docs/testing/stdio.md para um guia completo sobre como construir, executar e testar a implementação stdio (IDEs, MCP Inspector)
• Teste Remoto: Consulte docs/testing/remote.md para um guia completo sobre como testar o servidor remoto (OAuth, interface web, cliente CLI)

Notas de Desenvolvimento

Revisão Automatizada de Código

Este repositório usa ferramentas automatizadas de revisão de código (como Cursor BugBot) para ajudar a identificar possíveis problemas em pull requests. Essas ferramentas fornecem feedback e sugestões úteis, mas não recomendamos tornar essas verificações obrigatórias, pois a precisão ainda está evoluindo e pode produzir falsos positivos.

As revisões automatizadas devem ser tratadas como:

• ✅ Sugestões úteis a serem consideradas durante a revisão de código
• ✅ Pontos de partida para discussão e melhoria
• ❌ Não são requisitos bloqueadores para mesclar PRs
• ❌ Não substituem a revisão de código humana

Ao abordar o feedback automatizado, concentre-se nas preocupações subjacentes em vez de seguir estritamente cada sugestão.

Documentação para Contribuidores

Deseja contribuir ou explorar o mapa completo da documentação? Consulte CLAUDE.md (também disponível como AGENTS.md) para fluxos de trabalho do contribuidor e o índice completo de documentos. A pasta docs/ contém os guias por tópico e os arquivos .md integrados às ferramentas.