Sentry MCP

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

Sentry Toolkit

Dieses Repository enthält die Sentry CLI, den Sentry MCP-Server und gemeinsame Pakete. Für die CLI siehe den CLI-Leitfaden und die veröffentlichte Dokumentation unter https://cli.sentry.dev/. Der Dokumentationsindex deckt beide Produkte sowie gemeinsame Mitwirkungs-Anleitungen ab.

Sentry MCP

Der MCP-Dienst von Sentry ist in erster Linie für Coding-Agenten mit menschlicher Kontrolle (human-in-the-loop) konzipiert. Unsere Tool-Auswahl und Prioritäten konzentrieren sich auf Entwickler-Workflows und Debugging-Anwendungsfälle, nicht auf einen allgemeinen MCP-Server für alle Sentry-Funktionen.

Dieser entfernte MCP-Server fungiert als Middleware zur vorgelagerten Sentry-API und ist für Coding-Assistenten wie Cursor, Claude Code und ähnliche Entwicklungswerkzeuge optimiert. Er basiert auf Cloudflares Arbeit an entfernten MCPs.

Erste Schritte

Alles, was Sie wissen müssen, finden Sie, wenn Sie den bereitgestellten Dienst in der Produktion besuchen:

https://mcp.sentry.dev

Wenn Sie einen Beitrag leisten möchten, verstehen möchten, wie es funktioniert, oder dies für selbst gehostetes Sentry ausführen möchten, lesen Sie weiter unten.

Claude Code Plugin

Installieren Sie es als Claude Code-Plugin für die automatische Unteragenten-Delegierung:

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

Dies stellt einen sentry-mcp-Unteragenten bereit, an den Claude automatisch delegiert, wenn Sie nach Sentry-Fehlern, Issues, Traces oder Leistung fragen.

Für zukunftsorientierte Tool-Varianten und Funktionen:

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

Stdio vs. Remote

Während sich dieses Repository darauf konzentriert, als MCP-Dienst zu fungieren, unterstützen wir auch einen stdio-Transport. Dies ist noch in Arbeit, aber der einfachste Weg, den MCP gegen eine selbst gehostete Sentry-Installation anzupassen.

Hinweis: Die KI-gestützten Suchwerkzeuge (search_errors, search_traces, search_logs, search_issues usw.) erfordern einen LLM-Anbieter (OpenAI, Azure OpenAI, Anthropic oder OpenRouter). Diese Werkzeuge verwenden Verarbeitung natürlicher Sprache, um Abfragen in Sentrys Abfragesyntax zu übersetzen. Ohne einen konfigurierten Anbieter sind diese spezifischen Werkzeuge nicht verfügbar, aber alle anderen Werkzeuge funktionieren normal.

Um den stdio-Transport zu nutzen, müssen Sie ein Benutzer-Auth-Token in Sentry mit den erforderlichen Bereichen erstellen. Zum Zeitpunkt der Erstellung ist dies:

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

Starten Sie den Transport:

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

Müssen Sie eine Verbindung zu einer selbst gehosteten Bereitstellung herstellen? Fügen Sie --host hinzu (nur Hostname, z. B. --host=sentry.example.com), wenn Sie den Befehl ausführen. Für isolierte interne Bereitstellungen, die nur einfaches HTTP bereitstellen, fügen Sie außerdem --insecure-http hinzu.

Seer ist nicht Teil von selbst gehostetem Sentry, daher wird die seer-Fähigkeit aus dem Standard-Fähigkeitssatz ausgelassen, wann immer --host auf einen Nicht-sentry.io-Host zeigt. Wenn Ihre selbst gehostete Bereitstellung Seer ausführt, melden Sie sich explizit wieder an:

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

Sie können auch jede andere Fähigkeit deaktivieren, um zu verhindern, dass nicht unterstützte Werkzeuge bereitgestellt werden:

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

Für selbst gehostete Instanzen ohne TLS:

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

Remote mit explizitem Sentry-Token

Remote-Clients, die benutzerdefinierte HTTP-Header unterstützen, können ein vorgelagertes Sentry-API-Token direkt an den Cloudflare-Transport übergeben:

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

Sentry-Bearer ist absichtlich von Bearer getrennt: Bearer ist für MCP-OAuth-Zugriffstokens reserviert. Mit Sentry-Bearer speichert, validiert, tauscht oder aktualisiert der Worker das vorgelagerte Token nicht. Es leitet das Token über dieselben Sentry-API-Aufrufe weiter, die auch für OAuth-gestützte Sitzungen verwendet werden, und der Client oder der vorgelagerte Anbieter bleibt für die Token-Lebensdauer und -Aktualisierung verantwortlich.

Die direkte Remote-Authentifizierung verwendet standardmäßig alle aktiven MCP-Fähigkeiten. Sie können die bereitgestellten Werkzeuge mit ?skills=inspect,triage oder ?disable-skills=seer eingrenzen.

Umgebungsvariablen

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

Wichtig: Setzen Sie immer EMBEDDED_AGENT_PROVIDER, um Ihren LLM-Anbieter explizit anzugeben. Die automatische Erkennung basierend auf API-Schlüsseln allein ist veraltet und wird in einer zukünftigen Version entfernt. Siehe docs/operations/embedded-agents.md für detaillierte Konfigurationsoptionen.

Beispiel-MCP-Konfiguration

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

Wenn Sie die Host-Variable nicht gesetzt lassen, zielt die CLI automatisch auf den Sentry-SaaS-Dienst ab. Setzen Sie die Überschreibung nur, wenn Sie selbst gehostetes Sentry betreiben.

Das Setzen von SENTRY_HOST auf einen selbst gehosteten Host entfernt auch die seer-Fähigkeit aus dem Standardsatz, da Seer auf selbst gehostetem Sentry nicht verfügbar ist. Für eine selbst gehostete Bereitstellung, die Seer ausführt, melden Sie sich mit MCP_SKILLS an:

{
  "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 enthält einen Inspector, um den Dienst einfach zu testen:

pnpm inspector

Geben Sie die MCP-Server-URL (http://localhost:5173) ein und klicken Sie auf Verbinden. Dies sollte den Authentifizierungsablauf für Sie auslösen.

Hinweis: Wenn Sie Probleme mit Ihrem OAuth-Ablauf haben, wenn Sie auf den Inspector unter 127.0.0.1 zugreifen, versuchen Sie localhost stattdessen, indem Sie http://localhost:6274 besuchen.

Lokale Entwicklung

Um Änderungen beizutragen, müssen Sie Ihre lokale Umgebung einrichten:

1. Umgebung und Agent-Fähigkeiten einrichten:

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

   Dies führt auch npx @sentry/dotagents install aus, um gemeinsame Fähigkeiten aus getsentry/skills in .agents/skills/ zu installieren (symbolisch verknüpft in .claude/skills und .cursor/skills). Wenn Sie Fähigkeiten später aktualisieren müssen, führen Sie es direkt aus:

   npx @sentry/dotagents install
   

2. Eine OAuth-App in Sentry erstellen (Einstellungen => API => Anwendungen):

   • Homepage-URL: http://localhost:5173
   • Autorisierte Weiterleitungs-URIs: http://localhost:5173/oauth/callback
   • Notieren Sie Ihre Client-ID und generieren Sie ein Client-Geheimnis

3. Ihre Anmeldeinformationen konfigurieren:

   • Bearbeiten Sie .env im Stammverzeichnis und fügen Sie entweder OPENAI_API_KEY oder OPENROUTER_API_KEY hinzu
   • Bearbeiten Sie packages/mcp-cloudflare/.env und fügen Sie hinzu:
     • SENTRY_CLIENT_ID=your_development_sentry_client_id
     • SENTRY_CLIENT_SECRET=your_development_sentry_client_secret
     • COOKIE_SECRET=my-super-secret-cookie

4. Den Entwicklungsserver starten:

   pnpm dev
   

Verifizieren

Führen Sie den Server lokal aus, um ihn unter http://localhost:5173 verfügbar zu machen

pnpm dev

Um den lokalen Server zu testen, geben Sie http://localhost:5173/mcp in Inspector ein und klicken Sie auf Verbinden. Sobald Sie den Aufforderungen folgen, können Sie "Werkzeuge auflisten".

Tests

Es gibt drei Test-Suiten: Unit-Tests, Bewertungen und manuelles Testen.

Unit-Tests können mit folgendem Befehl ausgeführt werden:

pnpm test

Bewertungen erfordern eine .env-Datei im Projektstamm mit etwas Konfiguration:

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

Hinweis: Die Stammdatei .env bietet Standardwerte für alle Pakete. Einzelne Pakete können ihre eigenen .env-Dateien haben, um diese Standardwerte während der Entwicklung zu überschreiben.

Sobald das erledigt ist, können Sie sie mit folgendem Befehl ausführen:

pnpm eval

Manuelles Testen (bevorzugt zum Testen von MCP-Änderungen):

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

Hinweis: Die CLI verwendet standardmäßig http://localhost:5173. Überschreiben Sie mit --mcp-host oder setzen Sie die Umgebungsvariable MCP_URL.

Umfassende Test-Playbooks:

• Stdio-Tests: Siehe docs/testing/stdio.md für die vollständige Anleitung zum Erstellen, Ausführen und Testen der Stdio-Implementierung (IDEs, MCP Inspector)
• Remote-Tests: Siehe docs/testing/remote.md für die vollständige Anleitung zum Testen des Remote-Servers (OAuth, Web-UI, CLI-Client)

Entwicklungsnotizen

Automatisierte Code-Überprüfung

Dieses Repository verwendet automatisierte Code-Überprüfungswerkzeuge (wie Cursor BugBot), um potenzielle Probleme in Pull-Requests zu identifizieren. Diese Werkzeuge bieten hilfreiches Feedback und Vorschläge, aber wir empfehlen nicht, diese Prüfungen als erforderlich zu machen, da die Genauigkeit noch in der Entwicklung ist und falsch-positive Ergebnisse erzeugen kann.

Die automatisierten Überprüfungen sollten behandelt werden als:

• ✅ Hilfreiche Vorschläge, die während der Code-Überprüfung berücksichtigt werden sollten
• ✅ Ausgangspunkte für Diskussion und Verbesserung
• ❌ Keine blockierenden Anforderungen für das Zusammenführen von PRs
• ❌ Keine Ersatzlösungen für menschliche Code-Überprüfung

Wenn Sie auf automatisiertes Feedback eingehen, konzentrieren Sie sich auf die zugrunde liegenden Anliegen, anstatt strikt jedem Vorschlag zu folgen.

Mitwirkungs-Dokumentation

Möchten Sie einen Beitrag leisten? Beginnen Sie beim Toolkit-Dokumentationsindex für CLI-, MCP- und gemeinsame Anleitungen. Siehe AGENTS.md für Repository-Regeln und packages/cli/AGENTS.md für CLI-spezifische Regeln.