Sentry MCP

sentry-mcp

Sentrys MCP-Dienst 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 und nicht auf einen allgemeinen MCP-Server für die gesamte Sentry-Funktionalität.

Dieser Remote-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 Remote-MCPs.

Erste Schritte

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

https://mcp.sentry.dev

Wenn Sie einen Beitrag leisten möchten, erfahren 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 Subagenten-Delegation:

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 zukunftsorientierte Tool-Varianten und Funktionen:

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

Stdio vs. Remote

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

Hinweis: Die KI-gestützten Suchwerkzeuge (search_events, 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-Authentifizierungstoken in Sentry mit den erforderlichen Berechtigungen erstellen. Zum Zeitpunkt der Erstellung dieses Dokuments sind 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

Sie müssen sich mit einer selbst gehosteten Bereitstellung verbinden? Fügen Sie --host (nur Hostname, z. B. --host=sentry.example.com) hinzu, wenn Sie den Befehl ausführen. Fügen Sie für isolierte interne Bereitstellungen, die nur einfaches HTTP bereitstellen, außerdem --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 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 bewusst 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-Skills. 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
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. Detaillierte Konfigurationsoptionen finden Sie in docs/operations/embedded-agents.md.

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. 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 haben, wenn Sie auf den Inspector unter 127.0.0.1 zugreifen, versuchen Sie stattdessen localhost zu verwenden, indem Sie http://localhost:6274 besuchen.

Lokale Entwicklung

Um Änderungen beizusteuern, 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 gemeinsame Skills aus getsentry/skills in .agents/skills/ zu installieren (symbolisch verlinkt in .claude/skills und .cursor/skills). Wenn Sie die 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):

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

3. Konfigurieren Sie Ihre Anmeldedaten:

   • 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 Aufforderungen folgen, können Sie „List Tools" verwenden.

Tests

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

Unit-Tests können wie folgt ausgeführt werden:

pnpm test

Evaluierungen erfordern eine .env-Datei im Projektstammverzeichnis mit einiger 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 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 das erledigt ist, können Sie sie wie folgt ausführen:

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

Automatisiertes Code-Review

Dieses Repository verwendet automatisierte Code-Review-Tools (wie Cursor BugBot), um potenzielle Probleme in Pull Requests zu identifizieren. Diese Tools bieten hilfreiches Feedback und Vorschläge, aber wir empfehlen nicht, diese Prüfungen als Pflicht zu machen, da die Genauigkeit sich noch weiterentwickelt und falsch-positive Ergebnisse erzeugen kann.

Die automatisierten Reviews sollten wie folgt behandelt werden:

• ✅ Hilfreiche Vorschläge, die während des Code-Reviews berücksichtigt werden sollten
• ✅ Ausgangspunkte für Diskussion und Verbesserung
• ❌ Keine blockierenden Anforderungen für das Zusammenführen von PRs
• ❌ Kein Ersatz für menschliches Code-Review

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

Dokumentation für Mitwirkende

Möchten Sie einen Beitrag leisten oder die vollständige Dokumentationsübersicht erkunden? Siehe CLAUDE.md (auch verfügbar als AGENTS.md) für Contributor-Workflows und den vollständigen Dokumentationsindex. Der Ordner docs/ enthält die themenbezogenen Anleitungen und tool-integrierten .md-Dateien.