Sentry MCP

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

Sentry Toolkit

Este repositório contém a Sentry CLI, o servidor Sentry MCP e pacotes compartilhados. Para a CLI, consulte o guia da CLI e a documentação publicada em https://cli.sentry.dev/. O índice da documentação abrange ambos os produtos e as orientações compartilhadas para contribuidores.

O Docs MCP Worker independente oferece busca na documentação e respostas geradas por IA com base em docs.sentry.io.

Sentry MCP

O serviço MCP do Sentry é projetado principalmente para agentes de codificação com humano no loop. Nossa seleção de ferramentas e prioridades são focadas em fluxos de trabalho de desenvolvedores 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.

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, entender como funciona ou executar isto 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

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

Para variantes e recursos de ferramentas voltados ao 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. Isto ainda está em desenvolvimento, 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_errors, search_traces, search_logs, 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 ferramentas funcionarão normalmente.

Para utilizar o transporte stdio, você precisará criar um User Auth Token no Sentry com os escopos necessários. No momento da escrita, isto é:

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 conectar a uma implantação auto-hospedada? Adicione --host (somente 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.

O Seer não faz parte do Sentry auto-hospedado, portanto a skill seer fica de fora do conjunto padrão de skills sempre que --host aponta para um host que não é sentry.io. Se sua implantação auto-hospedada executar o Seer, opte por incluí-la novamente explicitamente:

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

Você também pode desabilitar qualquer outra skill para evitar que ferramentas não suportadas sejam expostas:

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

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 Sentry Explícito

Clientes remotos que suportam cabeçalhos HTTP personalizados podem passar um token da API upstream do Sentry diretamente para o transporte 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 à API do Sentry usadas por sessões com OAuth, e o cliente ou o provedor upstream permanece responsável pelo tempo de vida e atualização do token.

A autenticação remota direta usa por padrão todas as skills 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 (drops 'seer' from the default skills)
MCP_SKILLS=                  # Grant specific skills (comma-separated, e.g. 'inspect,seer')
MCP_DISABLE_SKILLS=          # Disable specific skills (comma-separated, e.g. 'project-management')

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 detalhadas de configuração.

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 indefinida, a CLI automaticamente aponta para o serviço Sentry SaaS. Defina a substituição apenas quando você operar um Sentry auto-hospedado.

Definir SENTRY_HOST para um host auto-hospedado também remove a skill seer do conjunto padrão, já que o Seer não está disponível no Sentry auto-hospedado. Para uma implantação auto-hospedada que executa o Seer, opte por incluí-la com MCP_SKILLS:

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

Limites de Taxa

As chamadas de ferramentas estão sujeitas aos limites de taxa da API do Sentry. O servidor MCP tenta novamente requisições limitadas por taxa, e erros transitórios do servidor Sentry em requisições de leitura, após uma breve espera. Quando um limite dura mais tempo, a ferramenta retorna uma mensagem de Rate Limited que informa quando tentar novamente. Os agentes atingem os limites por segundo com mais frequência ao executar muitas chamadas de ferramentas do Sentry em paralelo, portanto execute-as uma de cada vez se você vir esta mensagem.

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. Isto 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 em vez disso, visitando http://localhost:6274.

Desenvolvimento Local

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

1. Configure o ambiente e as skills do agente:

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

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

   npx @sentry/dotagents install
   

2. Crie um OAuth App no Sentry (Settings => API => Applications):

   • Homepage URL: http://localhost:5173
   • Authorized Redirect URIs: 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 torná-lo disponível 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á "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 .env na 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.

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

Playbooks abrangentes de teste:

• Teste stdio: Consulte docs/testing/stdio.md para um guia completo sobre como compilar, 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 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á evoluindo 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 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

Quer contribuir? Comece pelo índice da documentação do Toolkit para guias de CLI, MCP e compartilhados. Consulte AGENTS.md para as regras do repositório e packages/cli/AGENTS.md para regras específicas da CLI.