Sentry MCP

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 polyvalent pour toutes les fonctionnalités de Sentry.

Ce serveur MCP distant agit comme un intergiciel 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 des 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, apprendre comment cela fonctionne ou exécuter ceci pour une instance Sentry auto-hébergée, continuez ci-dessous.

Plugin Claude Code

Installez-le en tant que 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 auquel Claude délègue automatiquement lorsque vous posez des questions sur les erreurs, les problèmes, les traces ou les performances de Sentry.

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

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

Stdio vs Distant

Bien que ce dépôt soit axé sur le fait d'agir comme un 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 et d'exécuter le MCP sur une installation Sentry auto-hébergée.

Remarque : Les outils de recherche alimentés par l'IA (search_events, 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 en 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 d'écrire ces lignes, 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.

Certaines fonctionnalités (comme Seer) peuvent ne pas être disponibles sur les instances auto-hébergées. Vous pouvez désactiver des compétences spécifiques 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=seer

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

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

Distant 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 d'API Sentry utilisés par les sessions adossées à 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 active par défaut toutes les compétences MCP actives. Vous pouvez restreindre 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'

# Optional overrides
SENTRY_HOST=                 # For self-hosted deployments
MCP_DISABLE_SKILLS=          # Disable specific skills (comma-separated, e.g. 'seer')

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. Voir 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, l'interface en ligne de commande cible automatiquement le service SaaS Sentry. Ne définissez la substitution que lorsque vous utilisez une instance Sentry auto-hébergée.

Pour les instances auto-hébergées qui ne prennent pas en charge Seer :

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

Inspecteur MCP

MCP inclut un Inspecteur, 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. Configurer l'environnement et les compétences d'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é symboliquement dans .claude/skills et .cursor/skills). Si vous devez mettre à jour les compétences ultérieurement, exécutez-le directement :

   npx @sentry/dotagents install
   

2. Créer 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. Configurer vos informations d'identification :

   • 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émarrer le serveur de développement :

   pnpm dev
   

Vérifier

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 l'Inspecteur et cliquez sur connecter. Une fois que vous aurez suivi les invites, vous pourrez « Lister les outils ».

Tests

Il y a trois suites de tests incluses : tests unitaires, évaluations et tests manuels.

Les tests unitaires peuvent être exécutés en utilisant :

pnpm test

Les é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 des valeurs par défaut pour tous les paquets. Les paquets individuels peuvent avoir leurs propres fichiers .env pour remplacer ces valeurs par défaut pendant le développement.

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

pnpm eval

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

Remarque : L'interface en ligne de commande utilise par défaut http://localhost:5173. Remplacez par --mcp-host ou définissez la variable d'environnement MCP_URL.

Guides de test complets :

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

Notes de développement

Révision de code automatisée

Ce dépôt utilise des outils de révision de code automatisés (comme Cursor BugBot) pour aider à identifier les problèmes potentiels dans les demandes d'extraction. 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 révisions automatisées doivent être traitées comme :

• ✅ Des suggestions utiles à considérer lors de la révision du code
• ✅ Des points de départ pour la discussion et l'amélioration
• ❌ Pas des exigences bloquantes pour la fusion des PR
• ❌ Pas des remplacements pour la révision humaine du code

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

Documentation du contributeur

Vous cherchez à contribuer ou à explorer la carte complète de la documentation ? Voir CLAUDE.md (également disponible sous AGENTS.md) pour les flux de travail des contributeurs et l'index complet de la documentation. Le dossier docs/ contient les guides par sujet et les fichiers .md intégrés aux outils.