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 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 autres 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

Ceci 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 les variantes d'outils et 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 et d'exécuter le MCP contre une installation Sentry auto-hébergée.

Remarque : Les outils de recherche basés sur 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 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 scopes nécessaires. Au moment de la rédaction, voici ces scopes :

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 ex. --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

Remote avec un jeton Sentry explicite

Les clients distants qui prennent en charge les en-têtes HTTP personnalisés peuvent transmettre un jeton 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, ne valide, n'échange ni ne rafraîchit le jeton en amont. Il transmet le jeton via les mêmes appels API Sentry utilisés pour les sessions authentifiées par 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.6-luna'
OPENROUTER_REASONING_EFFORT= # Optional OpenRouter reasoning effort, defaults to 'high'

# 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 prochaine version. 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, la CLI cible automatiquement le service SaaS Sentry. Ne définissez la valeur de remplacement que lorsque vous opérez un Sentry auto-hébergé.

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"
      }
    }
  }
}

MCP Inspector

MCP inclut un Inspector pour tester facilement le service :

pnpm inspector

Saisissez 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 des 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ées en symlink 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é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 identifiant client et générez un secret client

3. Configurer 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émarrer 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, saisissez http://localhost:5173/mcp dans Inspector et cliquez sur connecter. Une fois que vous avez suivi les invites, vous pourrez « Lister les outils ».

Tests

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

Les tests unitaires peuvent être exécutés avec :

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

Les 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 : La CLI utilise par défaut http://localhost:5173. Remplacez avec --mcp-host ou définissez la variable d'environnement MCP_URL.

Playbooks de tests complets :

• Tests Stdio : Voir 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 distants : Voir 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 est encore en évolution et peut produire des faux positifs.

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

• ✅ Des suggestions utiles à considérer lors de la revue de code
• ✅ Des points de départ pour la discussion et l'amélioration
• ❌ Non bloquantes pour la fusion des PR
• ❌ Non des remplacements de 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 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 des documents. Le dossier docs/ contient les guides par sujet et les fichiers .md intégrés aux outils.