Sentry MCP

sentry-mcp

Der MCP-Dienst von Sentry ist in erster Linie für Coding-Agenten mit menschlicher Beteiligung (Human-in-the-Loop) konzipiert. Unsere Tool-Auswahl und Prioritäten konzentrieren sich auf Entwickler-Workflows und Debugging-Anwendungsfälle, anstatt einen universellen MCP-Server für die gesamte Sentry-Funktionalität bereitzustellen.

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

Erste Schritte

Alles Wissenswerte finden Sie beim Besuch des bereitgestellten Dienstes in der Produktion:

https://mcp.sentry.dev

Wenn Sie beitragen möchten, erfahren möchten, wie es funktioniert, oder dies für selbst gehostetes Sentry ausführen möchten, lesen Sie unten weiter.

Claude Code Plugin

Installieren Sie es als Claude Code Plugin für die automatische Delegation an Subagenten:

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

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

Für zukunftsweisende Tool-Varianten und Funktionen:

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

Stdio vs. Remote

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

Hinweis: Die KI-gestützten Suchwerkzeuge (search_events, search_issues usw.) erfordern einen LLM-Anbieter (OpenAI, Azure OpenAI, Anthropic oder OpenRouter). Diese Werkzeuge nutzen natürliche Sprachverarbeitung, um Abfragen in die Sentry-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 dieses Dokuments 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 (nur Hostname, z. B. --host=sentry.example.com) hinzu, wenn Sie den Befehl ausführen. Für isolierte interne Bereitstellungen, die nur einfaches HTTP bereitstellen, fügen Sie zusätzlich --insecure-http hinzu.

Einige Funktionen (wie Seer) sind auf selbst gehosteten Instanzen möglicherweise nicht verfügbar. Sie können bestimmte Skills 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=seer

Für selbst gehostete Instanzen ohne TLS:

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

Remote mit einem expliziten 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 bewusst von Bearer getrennt: Bearer ist reserviert für MCP-OAuth-Zugriffstoken. Mit Sentry-Bearer speichert, validiert, tauscht oder aktualisiert der Worker das vorgelagerte Token nicht. Er leitet das Token über dieselben Sentry-API-Aufrufe weiter, die von OAuth-gestützten Sitzungen verwendet werden, und der Client oder vorgelagerte Anbieter bleibt für die Token-Lebensdauer und -Aktualisierung verantwortlich.

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

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'

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

Wichtig: Setzen Sie immer EMBEDDED_AGENT_PROVIDER, um Ihren LLM-Anbieter explizit anzugeben. Die automatische Erkennung allein anhand von API-Schlüsseln 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 setzen, zielt die CLI automatisch auf den Sentry- SaaS-Dienst ab. Setzen Sie die Überschreibung nur, wenn Sie selbst gehostetes Sentry betreiben.

Für selbst gehostete Instanzen, die Seer nicht unterstützen:

{
  "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 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 beim Zugriff auf den Inspector auf 127.0.0.1 haben, versuchen Sie stattdessen localhost zu verwenden, indem Sie http://localhost:6274 besuchen.

Lokale Entwicklung

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

1. Umgebung und Agenten-Skills einrichten:

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

   Dies führt auch npx @sentry/dotagents install aus, um gemeinsam genutzte Skills von getsentry/skills in .agents/skills/ zu installieren (symverknüpft in .claude/skills und .cursor/skills). Wenn Sie Skills später aktualisieren müssen, führen Sie es direkt aus:

   npx @sentry/dotagents install
   

2. Erstellen Sie eine OAuth-App in Sentry (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. Konfigurieren Sie Ihre Anmeldeinformationen:

   • 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. Starten Sie den Entwicklungsserver:

   pnpm dev
   

Überprüfen

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 den Inspector ein und klicken Sie auf Verbinden. Sobald Sie den Anweisungen folgen, können Sie "Werkzeuge auflisten".

Tests

Es sind drei Test-Suiten enthalten: Unit-Tests, Evaluierungen und manuelle Tests.

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

pnpm test

Evaluierungen erfordern eine .env Datei im Projektstammverzeichnis 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 .env Datei im Stammverzeichnis stellt Standardwerte für alle Pakete bereit. Einzelne Pakete können ihre eigenen .env Dateien haben, um diese Standardwerte während der Entwicklung zu überschreiben.

Sobald dies erledigt ist, können Sie sie ausführen mit:

pnpm eval

Manuelle Tests (bevorzugt zum Testen von MCP-Änderungen):

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

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

Entwicklungshinweise

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 verpflichtend zu machen, da die Genauigkeit sich noch entwickelt und falsch-positive Ergebnisse liefern 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 Mergen von PRs
• ❌ Kein Ersatz für menschliche Code-Überprüfung

Konzentrieren Sie sich bei der Bearbeitung von automatisiertem Feedback auf die zugrunde liegenden Anliegen, anstatt jeden Vorschlag strikt zu befolgen.

Dokumentation für Mitwirkende

Möchten Sie beitragen oder die vollständige Dokumentationsübersicht erkunden? Siehe CLAUDE.md (auch verfügbar als AGENTS.md) für Mitwirkenden-Workflows und den vollständigen Dokumentationsindex. Der Ordner docs/ enthält die themenspezifischen Anleitungen und toolintegrierten .md Dateien.