Sentry MCP

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

Sentry Toolkit

Este repositorio contiene la CLI de Sentry, el servidor MCP de Sentry y paquetes compartidos. Para la CLI, consulta la guía de CLI y la documentación publicada en https://cli.sentry.dev/. El índice de documentación cubre tanto los productos como la guía de contribución compartida.

Sentry MCP

El servicio MCP de Sentry está diseñado principalmente para agentes de codificación con supervisión humana. Nuestra selección de herramientas y prioridades se centran en flujos de trabajo de desarrolladores 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 MCP 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 Sentry autoalojado, continúa abajo.

Plugin de Claude Code

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

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

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

Para variantes de herramientas y características orientadas al futuro:

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

Stdio vs Remoto

Aunque este repositorio se centra en actuar como un servicio MCP, también admitimos un transporte stdio. Esto sigue siendo un trabajo en progreso, pero es la forma más fácil de adaptar y ejecutar el MCP contra una instalación de Sentry autoalojada.

Nota: Las herramientas de búsqueda impulsadas por IA (search_errors, search_traces, search_logs, search_issues, etc.) requieren un proveedor de LLM (OpenAI, Azure OpenAI, Anthropic u OpenRouter). Estas herramientas utilizan 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 con normalidad.

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

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 una implementación autoalojada? Agrega --host (solo nombre de host, por ejemplo, --host=sentry.example.com) cuando ejecutes el comando. Para implementaciones internas aisladas que solo exponen HTTP simple, agrega también --insecure-http.

Seer no forma parte de Sentry autoalojado, por lo que la habilidad seer se excluye del conjunto de habilidades predeterminado siempre que --host apunte a un host que no sea sentry.io. Si tu implementación autoalojada ejecuta Seer, vuelve a optar por ella explícitamente:

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

También puedes deshabilitar cualquier otra habilidad para evitar que se expongan herramientas no compatibles:

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

Para instancias autoalojadas sin TLS:

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

Remoto con un Token de Sentry Explícito

Los clientes remotos que admiten encabezados HTTP personalizados 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 actualiza el token ascendente. Lo reenvía a través de las mismas llamadas a la API de Sentry utilizadas por las sesiones respaldadas por OAuth, y el cliente o el proveedor ascendente sigue siendo responsable de la vida útil y la actualización del token.

La autenticación remota directa utiliza por defecto todas las habilidades MCP activas. Puedes reducir 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.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: Siempre establece EMBEDDED_AGENT_PROVIDER para especificar explícitamente tu proveedor de LLM. La detección automática basada únicamente en claves de 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 de host sin configurar, la CLI apunta automáticamente al servicio SaaS de Sentry. Solo establece la anulación cuando operes Sentry autoalojado.

Establecer SENTRY_HOST a un host autoalojado también elimina la habilidad seer del conjunto predeterminado, ya que Seer no está disponible en Sentry autoalojado. Para una implementación autoalojada que ejecute Seer, opta por ella con 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"
      }
    }
  }
}

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 por 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. Configura 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/ (enlazadas simbólicamente en .claude/skills y .cursor/skills). Si necesitas actualizar las habilidades más tarde, ejecútalo directamente:

   npx @sentry/dotagents install
   

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

   • URL de página de inicio: http://localhost:5173
   • URI de redirección autorizados: http://localhost:5173/oauth/callback
   • Anota tu ID de cliente y genera un secreto de cliente

3. Configura tus credenciales:

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

4. Inicia el servidor de desarrollo:

   pnpm dev
   

Verificación

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 Inspector y haz clic en conectar. Una vez que sigas las indicaciones, podrás "Listar Herramientas".

Pruebas

Hay tres conjuntos de pruebas incluidos: pruebas unitarias, evaluaciones y pruebas manuales.

Pruebas unitarias se pueden ejecutar usando:

pnpm test

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 .env raíz proporciona valores predeterminados para todos los paquetes. Los paquetes individuales pueden tener sus propios archivos .env para anular estos valores predeterminados 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 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. Anula con --mcp-host o establece la variable de entorno MCP_URL.

Manuales de pruebas integrales:

• Pruebas Stdio: Consulta docs/testing/stdio.md para la guía completa sobre compilar, ejecutar y probar la implementación stdio (IDEs, Inspector MCP)
• Pruebas remotas: Consulta docs/testing/remote.md para la guía completa sobre probar el servidor remoto (OAuth, interfaz web, cliente CLI)

Notas de Desarrollo

Revisión de Código Automatizada

Este repositorio utiliza herramientas de revisión de código automatizadas (como Cursor BugBot) para ayudar a identificar problemas potenciales en las solicitudes de extracción. Estas herramientas proporcionan comentarios y sugerencias útiles, pero no recomendamos hacer que estas verificaciones 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 para la revisión de código humana

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

Documentación para Contribuyentes

¿Buscas contribuir? Comienza en el índice de documentación del Toolkit para guías de CLI, MCP y compartidas. Consulta AGENTS.md para las reglas del repositorio y packages/cli/AGENTS.md para las reglas específicas de la CLI.