Sentry MCP

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

Sentry Toolkit

Ce dépôt contient le CLI Sentry, le serveur MCP Sentry et des packages partagés. Pour le CLI, consultez le guide CLI et la documentation publiée à https://cli.sentry.dev/. L'index de documentation couvre à la fois les produits et les conseils de contribution partagés.

Sentry MCP

Le service MCP de Sentry est principalement conçu pour les agents de codage avec intervention humaine. Notre sélection d'outils et nos priorités sont axées sur les flux de travail des développeurs et les cas d'utilisation de débogage, plutôt que de fournir un serveur MCP généraliste pour toutes les fonctionnalités de Sentry.

Ce serveur MCP distant agit comme un intermédiaire vers l'API Sentry en amont, optimisé pour les assistants de codage comme Cursor, Claude Code et des outils de développement similaires. Il est basé sur le travail de Cloudflare vers les MCP distants.

Pour commencer

Vous trouverez tout ce que vous devez savoir en visitant le service déployé en production :

https://mcp.sentry.dev

Si vous souhaitez contribuer, comprendre son fonctionnement ou l'exécuter pour Sentry auto-hébergé, continuez ci-dessous.

Plugin Claude Code

Installez-le comme plugin Claude Code pour la délégation automatique de sous-agents :

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

Cela fournit un sous-agent sentry-mcp que Claude délègue automatiquement lorsque vous posez des questions sur les erreurs, les problèmes, les traces ou les performances de Sentry.

Pour les variantes d'outils et les fonctionnalités tournées vers l'avenir :

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

Stdio vs Remote

Bien que ce dépôt soit axé sur le rôle de service MCP, nous prenons également en charge un transport stdio. C'est encore un travail en cours, mais c'est le moyen le plus simple d'adapter l'exécution du MCP à une installation Sentry auto-hébergée.

Remarque : Les outils de recherche basés sur l'IA (search_errors, search_traces, search_logs, search_issues, etc.) nécessitent un fournisseur LLM (OpenAI, Azure OpenAI, Anthropic ou OpenRouter). Ces outils utilisent le traitement du langage naturel pour traduire les requêtes dans la syntaxe de requête de Sentry. Sans fournisseur configuré, ces outils spécifiques seront indisponibles, mais tous les autres outils fonctionneront normalement.

Pour utiliser le transport stdio, vous devrez créer un jeton d'authentification utilisateur dans Sentry avec les portées nécessaires. Au moment de la rédaction, c'est :

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

Lancez le transport :

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

Besoin de vous connecter à un déploiement auto-hébergé ? Ajoutez --host (nom d'hôte uniquement, par exemple --host=sentry.example.com) lorsque vous exécutez la commande. Pour les déploiements internes isolés qui n'exposent que du HTTP simple, ajoutez également --insecure-http.

Seer ne fait pas partie de Sentry auto-hébergé, donc la compétence seer est laissée de côté dans l'ensemble de compétences par défaut chaque fois que --host pointe vers un hôte non-sentry.io. Si votre déploiement auto-hébergé exécute Seer, réactivez-le explicitement :

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

Vous pouvez également désactiver toute autre compétence pour empêcher l'exposition d'outils non pris en charge :

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

Pour les instances auto-hébergées sans TLS :

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

Remote avec un jeton Sentry explicite

Les clients distants qui prennent en charge les en-têtes HTTP personnalisés peuvent transmettre un jeton d'API Sentry en amont directement au transport Cloudflare :

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

Sentry-Bearer est intentionnellement séparé de Bearer : Bearer est réservé aux jetons d'accès OAuth MCP. Avec Sentry-Bearer, le worker ne stocke pas, ne valide pas, n'échange pas et ne rafraîchit pas le jeton en amont. Il transmet le jeton via les mêmes appels API Sentry utilisés par les sessions basées sur OAuth, et le client ou le fournisseur en amont reste responsable de la durée de vie et du rafraîchissement du jeton.

L'authentification distante directe est par défaut activée pour toutes les compétences MCP actives. Vous pouvez réduire les outils exposés avec ?skills=inspect,triage ou ?disable-skills=seer.

Variables d'environnement

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')

Important : Définissez toujours EMBEDDED_AGENT_PROVIDER pour spécifier explicitement votre fournisseur LLM. La détection automatique basée uniquement sur les clés API est obsolète et sera supprimée dans une version future. Consultez docs/operations/embedded-agents.md pour les options de configuration détaillées.

Exemple de configuration MCP

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

Si vous laissez la variable d'hôte non définie, le CLI cible automatiquement le service Sentry SaaS. Ne définissez la substitution que lorsque vous utilisez Sentry auto-hébergé.

Définir SENTRY_HOST sur un hôte auto-hébergé supprime également la compétence seer de l'ensemble par défaut, car Seer n'est pas disponible sur Sentry auto-hébergé. Pour un déploiement auto-hébergé qui exécute Seer, activez avec 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"
      }
    }
  }
}

MCP Inspector

MCP inclut un Inspector, pour tester facilement le service :

pnpm inspector

Entrez l'URL du serveur MCP (http://localhost:5173) et cliquez sur connecter. Cela devrait déclencher le flux d'authentification pour vous.

Remarque : Si vous rencontrez des problèmes avec votre flux OAuth lors de l'accès à l'inspecteur sur 127.0.0.1, essayez d'utiliser localhost à la place en visitant http://localhost:6274.

Développement local

Pour contribuer aux modifications, vous devrez configurer votre environnement local :

1. Configurez l'environnement et les compétences de l'agent :

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

   Cela exécute également npx @sentry/dotagents install pour installer les compétences partagées depuis getsentry/skills dans .agents/skills/ (liées symboliquement dans .claude/skills et .cursor/skills). Si vous devez mettre à jour les compétences plus tard, exécutez-le directement :

   npx @sentry/dotagents install
   

2. Créez une application OAuth dans Sentry (Paramètres => API => Applications) :

   • URL de la page d'accueil : http://localhost:5173
   • URI de redirection autorisés : http://localhost:5173/oauth/callback
   • Notez votre ID client et générez un secret client

3. Configurez vos identifiants :

   • Modifiez .env dans le répertoire racine et ajoutez soit OPENAI_API_KEY soit OPENROUTER_API_KEY
   • Modifiez packages/mcp-cloudflare/.env et ajoutez :
     • SENTRY_CLIENT_ID=your_development_sentry_client_id
     • SENTRY_CLIENT_SECRET=your_development_sentry_client_secret
     • COOKIE_SECRET=my-super-secret-cookie

4. Démarrez le serveur de développement :

   pnpm dev
   

Vérification

Exécutez le serveur localement pour le rendre disponible à http://localhost:5173

pnpm dev

Pour tester le serveur local, entrez http://localhost:5173/mcp dans Inspector et cliquez sur connecter. Une fois que vous suivez les invites, vous pourrez « Lister les outils ».

Tests

Trois suites de tests sont incluses : tests unitaires, évaluations et tests manuels.

Tests unitaires peuvent être exécutés avec :

pnpm test

Évaluations nécessitent un fichier .env à la racine du projet avec une certaine configuration :

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

Remarque : Le fichier .env racine fournit les valeurs par défaut pour tous les packages. Chaque package peut avoir ses propres fichiers .env pour remplacer ces valeurs par défaut pendant le développement.

Une fois cela fait, vous pouvez les exécuter avec :

pnpm eval

Tests manuels (préférés pour tester les modifications 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"

Remarque : Le CLI utilise par défaut http://localhost:5173. Remplacez avec --mcp-host ou définissez la variable d'environnement MCP_URL.

Playbooks de test complets :

• Tests Stdio : Consultez docs/testing/stdio.md pour le guide complet sur la construction, l'exécution et le test de l'implémentation stdio (IDE, MCP Inspector)
• Tests Remote : Consultez docs/testing/remote.md pour le guide complet sur le test du serveur distant (OAuth, interface web, client CLI)

Notes de développement

Revue de code automatisée

Ce dépôt utilise des outils de revue de code automatisés (comme Cursor BugBot) pour aider à identifier les problèmes potentiels dans les demandes de tirage. Ces outils fournissent des retours et des suggestions utiles, mais nous ne recommandons pas de rendre ces vérifications obligatoires car la précision évolue encore et peut produire des faux positifs.

Les revues automatisées doivent être traitées comme :

• ✅ Suggestions utiles à considérer lors de la revue de code
• ✅ Points de départ pour la discussion et l'amélioration
• ❌ Exigences non bloquantes pour la fusion des PR
• ❌ Pas des remplacements pour la revue de code humaine

Lorsque vous traitez les retours automatisés, concentrez-vous sur les préoccupations sous-jacentes plutôt que de suivre strictement chaque suggestion.

Documentation pour les contributeurs

Vous souhaitez contribuer ? Commencez par l'index de documentation Toolkit pour les guides CLI, MCP et partagés. Consultez AGENTS.md pour les règles du dépôt et packages/cli/AGENTS.md pour les règles spécifiques au CLI.