Sentry MCP

npx add-mcp 'https://mcp.sentry.dev/mcp'

sentry-mcp

O serviço MCP do Sentry é projetado principalmente para agentes de codificação com intervenção humana. Nossa seleção de ferramentas e prioridades sã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 toda a funcionalidade 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 semelhantes. Ele é baseado no trabalho da Cloudflare em direção a MCPs remotos.

Introdução

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 o 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 que o Claude delega automaticamente quando você pergunta sobre erros, problemas, traces ou desempenho do Sentry.

Para variantes e recursos de ferramentas 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 suportamos um transporte stdio. Isso ainda está em andamento, mas é a maneira mais fácil de adaptar e executar o MCP contra 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 na sintaxe de consulta do Sentry. Sem um provedor configurado, essas ferramentas específicas ficarão indisponíveis, mas todas as outras 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 documento foi escrito, são:

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 (somente o hostname, ex.: --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 do Sentry Explícito

Clientes remotos que suportam cabeçalhos HTTP personalizados podem passar um token da API do Sentry upstream diretamente para o transporte do 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 baseadas em OAuth, e o cliente ou provedor upstream permanece responsável pela vida útil e atualização do token.

A autenticação remota direta usa, por 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.6-luna'
OPENROUTER_REASONING_EFFORT= # Optional OpenRouter reasoning effort, defaults to 'high'

# 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. Veja docs/operations/embedded-agents.md para opções detalhadas de configuração.

Exemplo de Configuração do 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 o override somente quando operar um 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"
      }
    }
  }
}

Inspetor do MCP

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

pnpm inspector

Digite 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 inspetor 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/ (symlink para .claude/skills e .cursor/skills). Se precisar atualizar habilidades depois, execute 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 Client ID e gere um Client secret

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
   

Verificação

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

pnpm dev

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

Testes

Há três suítes de testes 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 raiz .env fornece padrões para todos os pacotes. Pacotes individuais podem ter seus próprios arquivos .env para substituir esses padrões durante o desenvolvimento.

Depois de feito, 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 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 por padrão http://localhost:5173. Substitua com --mcp-host ou defina a variável de ambiente MCP_URL.

Playbooks de teste abrangentes:

• Testes Stdio: Veja docs/testing/stdio.md para o guia completo sobre construção, execução e teste da implementação stdio (IDEs, MCP Inspector)
• Testes remotos: Veja docs/testing/remote.md para o guia completo sobre teste do servidor remoto (OAuth, interface web, cliente CLI)

Notas de Desenvolvimento

Revisão de Código Automatizada

Este repositório usa ferramentas de revisão de código automatizadas (como o 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á em evolução e pode produzir falsos positivos.

As revisões automatizadas devem ser tratadas como:

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

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

Documentação para Contribuidores

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