Sentry MCP

sentry-mcp

El servicio MCP de Sentry está diseñado principalmente para agentes de codificación con intervención humana. Nuestra selección de herramientas y prioridades se centran en flujos de trabajo de desarrollo y casos de uso de depuración, en lugar de proporcionar un servidor MCP de propósito general para toda la funcionalidad de Sentry.

Este servidor MCP remoto actúa como middleware para la API de Sentry, optimizado para asistentes de codificación como Cursor, Claude Code y herramientas de desarrollo similares. Está basado en el trabajo de Cloudflare hacia MCPs remotos.

Primeros pasos

Encontrarás todo lo que necesitas saber visitando el servicio desplegado en producción:

https://mcp.sentry.dev

Si buscas contribuir, aprender cómo funciona o ejecutar esto para una instalación autogestionada de Sentry, continúa más abajo.

Plugin de Claude Code

Instálalo como un plugin de Claude Code para delegación automática en subagentes:

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

Esto proporciona un subagente sentry-mcp al que Claude delega automáticamente cuando preguntas sobre errores, incidencias, trazas o rendimiento de Sentry.

Para variantes de herramientas y características en desarrollo:

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

Stdio vs Remoto

Aunque este repositorio se centra en actuar como un servicio MCP, también soportamos un transporte stdio. Esto todavía está en desarrollo, pero es la forma más fácil de adaptar y ejecutar el MCP contra una instalación autogestionada de Sentry.

Nota: Las herramientas de búsqueda impulsadas por IA (search_events, search_issues, etc.) requieren un proveedor LLM (OpenAI, Azure OpenAI, Anthropic u OpenRouter). Estas herramientas usan procesamiento de lenguaje natural para traducir consultas a la sintaxis de consulta de Sentry. Sin un proveedor configurado, estas herramientas específicas no estarán disponibles, pero todas las demás funcionarán normalmente.

Para utilizar el transporte stdio, necesitarás crear un Token de Autenticación de Usuario en Sentry con los permisos necesarios. Al momento de escribir esto es:

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

Inicia el transporte:

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

¿Necesitas conectarte a un despliegue autogestionado? Añade --host (solo el nombre del host, ej. --host=sentry.example.com) cuando ejecutes el comando. Para despliegues internos aislados que solo exponen HTTP simple, añade también --insecure-http.

Algunas características (como Seer) pueden no estar disponibles en instancias autogestionadas. Puedes deshabilitar habilidades específicas para evitar que se expongan herramientas no soportadas:

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

Para instancias autogestionadas sin TLS:

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

Remoto con un Token Explícito de Sentry

Los clientes remotos que soportan cabeceras HTTP personalizadas pueden pasar un token de API de Sentry directamente al transporte de Cloudflare:

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

Sentry-Bearer está intencionalmente separado de Bearer: Bearer está reservado para tokens de acceso OAuth de MCP. Con Sentry-Bearer, el worker no almacena, valida, intercambia ni refresca el token de upstream. Reenvía el token a través de las mismas llamadas a la API de Sentry usadas por sesiones respaldadas por OAuth, y el cliente o proveedor upstream sigue siendo responsable del ciclo de vida y refresco del token.

La autenticación remota directa usa por defecto todas las habilidades MCP activas. Puedes limitar las herramientas expuestas con ?skills=inspect,triage o ?disable-skills=seer.

Variables de Entorno

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: Siempre configura EMBEDDED_AGENT_PROVIDER para especificar explícitamente tu proveedor LLM. La detección automática basada solo en claves API está obsoleta y se eliminará en una versión futura. Consulta docs/operations/embedded-agents.md para opciones de configuración detalladas.

Ejemplo de Configuración MCP

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

Si dejas la variable host sin configurar, la CLI apunta automáticamente al servicio SaaS de Sentry. Solo establece la sobrescritura cuando operes Sentry autogestionado.

Para instancias autogestionadas que no soportan Seer:

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

Inspector MCP

MCP incluye un Inspector, para probar fácilmente el servicio:

pnpm inspector

Ingresa la URL del servidor MCP (http://localhost:5173) y haz clic en conectar. Esto debería activar el flujo de autenticación para ti.

Nota: Si tienes problemas con tu flujo OAuth al acceder al inspector en 127.0.0.1, intenta usar localhost visitando http://localhost:6274.

Desarrollo Local

Para contribuir con cambios, necesitarás configurar tu entorno local:

1. Configurar el entorno y las habilidades del agente:

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

   Esto también ejecuta npx @sentry/dotagents install para instalar habilidades compartidas desde getsentry/skills en .agents/skills/ (enlazado simbólicamente en .claude/skills y .cursor/skills). Si necesitas actualizar las habilidades más tarde, ejecútalo directamente:

   npx @sentry/dotagents install
   

2. Crear una Aplicación OAuth en Sentry (Configuración => API => Aplicaciones):

   • URL de Inicio: http://localhost:5173
   • URIs de Redirección Autorizadas: http://localhost:5173/oauth/callback
   • Anota tu Client ID y genera un Client secret

3. Configurar tus credenciales:

   • Edita .env en el directorio raíz y añade OPENAI_API_KEY o OPENROUTER_API_KEY
   • Edita packages/mcp-cloudflare/.env y añade:
     • SENTRY_CLIENT_ID=your_development_sentry_client_id
     • SENTRY_CLIENT_SECRET=your_development_sentry_client_secret
     • COOKIE_SECRET=my-super-secret-cookie

4. Iniciar el servidor de desarrollo:

   pnpm dev
   

Verificar

Ejecuta el servidor localmente para que esté disponible en http://localhost:5173

pnpm dev

Para probar el servidor local, ingresa http://localhost:5173/mcp en el Inspector y haz clic en conectar. Una vez que sigas las indicaciones, podrás "Listar Herramientas".

Pruebas

Se incluyen tres conjuntos de pruebas: pruebas unitarias, evaluaciones y pruebas manuales.

Las pruebas unitarias se pueden ejecutar usando:

pnpm test

Las evaluaciones requieren un archivo .env en la raíz del proyecto con algo de configuración:

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

Nota: El archivo raíz .env proporciona valores predeterminados para todos los paquetes. Los paquetes individuales pueden tener sus propios archivos .env para sobrescribir estos valores durante el desarrollo.

Una vez hecho esto, puedes ejecutarlas usando:

pnpm eval

Pruebas manuales (preferidas para probar cambios en 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: La CLI usa por defecto http://localhost:5173. Sobrescribe con --mcp-host o configura la variable de entorno MCP_URL.

Guías de prueba completas:

• Pruebas Stdio: Consulta docs/testing/stdio.md para una guía completa sobre construcción, ejecución y prueba de la implementación stdio (IDEs, Inspector MCP)
• Pruebas Remotas: Consulta docs/testing/remote.md para una guía completa sobre pruebas del servidor remoto (OAuth, interfaz web, cliente CLI)

Notas de Desarrollo

Revisión Automatizada de Código

Este repositorio utiliza herramientas de revisión de código automatizadas (como Cursor BugBot) para ayudar a identificar posibles problemas en las pull requests. Estas herramientas proporcionan comentarios y sugerencias útiles, pero no recomendamos hacer que estas comprobaciones sean obligatorias ya que la precisión aún está evolucionando y puede producir falsos positivos.

Las revisiones automatizadas deben tratarse como:

• ✅ Sugerencias útiles a considerar durante la revisión de código
• ✅ Puntos de partida para discusión y mejora
• ❌ No son requisitos bloqueantes para fusionar PRs
• ❌ No son reemplazos de la revisión de código humana

Al abordar comentarios automatizados, céntrate en las preocupaciones subyacentes en lugar de seguir estrictamente cada sugerencia.

Documentación para Contribuidores

¿Buscas contribuir o explorar el mapa completo de documentación? Consulta CLAUDE.md (también disponible como AGENTS.md) para flujos de trabajo de contribuidores y el índice completo de documentos. La carpeta docs/ contiene las guías por tema y los archivos .md integrados con herramientas.