Sentry MCP

sentry-mcp

Layanan MCP Sentry terutama dirancang untuk agen pengkodean dengan manusia dalam lingkaran. Pemilihan alat dan prioritas kami difokuskan pada alur kerja pengembang dan kasus penggunaan debugging, bukan menyediakan server MCP tujuan umum untuk semua fungsionalitas Sentry.

Server MCP jarak jauh ini bertindak sebagai middleware ke API Sentry hulu, dioptimalkan untuk asisten pengkodean seperti Cursor, Claude Code, dan alat pengembangan serupa. Ini didasarkan pada pekerjaan Cloudflare menuju MCP jarak jauh.

Memulai

Anda akan menemukan semua yang perlu diketahui dengan mengunjungi layanan yang diterapkan di produksi:

https://mcp.sentry.dev

Jika Anda ingin berkontribusi, mempelajari cara kerjanya, atau menjalankan ini untuk Sentry yang dihosting sendiri, lanjutkan di bawah.

Plugin Claude Code

Instal sebagai plugin Claude Code untuk delegasi subagen otomatis:

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

Ini menyediakan subagen sentry-mcp yang secara otomatis didelegasikan oleh Claude ketika Anda bertanya tentang kesalahan, isu, jejak, atau kinerja Sentry.

Untuk varian alat dan fitur yang berwawasan ke depan:

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

Stdio vs Jarak Jauh

Meskipun repositori ini difokuskan untuk bertindak sebagai layanan MCP, kami juga mendukung transport stdio. Ini masih dalam proses, tetapi merupakan cara termudah untuk mengadaptasi dan menjalankan MCP terhadap instalasi Sentry yang dihosting sendiri.

Catatan: Alat pencarian bertenaga AI (search_events, search_issues, dll.) memerlukan penyedia LLM (OpenAI, Azure OpenAI, Anthropic, atau OpenRouter). Alat-alat ini menggunakan pemrosesan bahasa alami untuk menerjemahkan kueri ke dalam sintaks kueri Sentry. Tanpa penyedia yang dikonfigurasi, alat-alat spesifik ini tidak akan tersedia, tetapi semua alat lainnya akan berfungsi normal.

Untuk memanfaatkan transport stdio, Anda perlu membuat Token Auth Pengguna di Sentry dengan cakupan yang diperlukan. Saat tulisan ini dibuat, yaitu:

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

Luncurkan transport:

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

Perlu terhubung ke penerapan yang dihosting sendiri? Tambahkan --host (hanya nama host, misalnya --host=sentry.example.com) saat Anda menjalankan perintah. Untuk penerapan internal terisolasi yang hanya mengekspos HTTP biasa, tambahkan juga --insecure-http.

Beberapa fitur (seperti Seer) mungkin tidak tersedia pada instance yang dihosting sendiri. Anda dapat menonaktifkan keterampilan tertentu untuk mencegah alat yang tidak didukung diekspos:

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

Untuk instance yang dihosting sendiri tanpa TLS:

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

Jarak Jauh dengan Token Sentry Eksplisit

Klien jarak jauh yang mendukung header HTTP kustom dapat meneruskan token API Sentry hulu langsung ke transport Cloudflare:

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

Sentry-Bearer sengaja dipisahkan dari Bearer: Bearer dicadangkan untuk token akses OAuth MCP. Dengan Sentry-Bearer, worker tidak menyimpan, memvalidasi, menukar, atau menyegarkan token hulu. Ini meneruskan token melalui panggilan API Sentry yang sama yang digunakan oleh sesi yang didukung OAuth, dan klien atau penyedia hulu tetap bertanggung jawab atas masa pakai dan penyegaran token.

Auth jarak jauh langsung default ke semua keterampilan MCP aktif. Anda dapat mempersempit alat yang diekspos dengan ?skills=inspect,triage atau ?disable-skills=seer.

Variabel Lingkungan

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

Penting: Selalu atur EMBEDDED_AGENT_PROVIDER untuk secara eksplisit menentukan penyedia LLM Anda. Deteksi otomatis berdasarkan kunci API saja sudah usang dan akan dihapus di rilis mendatang. Lihat docs/operations/embedded-agents.md untuk opsi konfigurasi terperinci.

Contoh Konfigurasi MCP

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

Jika Anda membiarkan variabel host tidak disetel, CLI secara otomatis menargetkan layanan SaaS Sentry. Hanya atur override saat Anda mengoperasikan Sentry yang dihosting sendiri.

Untuk instance yang dihosting sendiri yang tidak mendukung Seer:

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

Inspektur MCP

MCP menyertakan Inspektur, untuk menguji layanan dengan mudah:

pnpm inspector

Masukkan URL server MCP (http://localhost:5173) dan tekan hubungkan. Ini seharusnya memicu alur autentikasi untuk Anda.

Catatan: Jika Anda memiliki masalah dengan alur OAuth saat mengakses inspektur di 127.0.0.1, coba gunakan localhost dengan mengunjungi http://localhost:6274.

Pengembangan Lokal

Untuk berkontribusi perubahan, Anda perlu menyiapkan lingkungan lokal Anda:

1. Siapkan lingkungan dan keterampilan agen:

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

   Ini juga menjalankan npx @sentry/dotagents install untuk menginstal keterampilan bersama dari getsentry/skills ke dalam .agents/skills/ (symlink ke .claude/skills dan .cursor/skills). Jika Anda perlu memperbarui keterampilan nanti, jalankan langsung:

   npx @sentry/dotagents install
   

2. Buat Aplikasi OAuth di Sentry (Pengaturan => API => Aplikasi):

   • URL Beranda: http://localhost:5173
   • URI Pengalihan Resmi: http://localhost:5173/oauth/callback
   • Catat ID Klien Anda dan buat rahasia Klien

3. Konfigurasikan kredensial Anda:

   • Edit .env di direktori root dan tambahkan OPENAI_API_KEY atau OPENROUTER_API_KEY
   • Edit packages/mcp-cloudflare/.env dan tambahkan:
     • SENTRY_CLIENT_ID=your_development_sentry_client_id
     • SENTRY_CLIENT_SECRET=your_development_sentry_client_secret
     • COOKIE_SECRET=my-super-secret-cookie

4. Mulai server pengembangan:

   pnpm dev
   

Verifikasi

Jalankan server secara lokal agar tersedia di http://localhost:5173

pnpm dev

Untuk menguji server lokal, masukkan http://localhost:5173/mcp ke Inspektur dan tekan hubungkan. Setelah Anda mengikuti petunjuk, Anda akan dapat "Mendaftar Alat".

Pengujian

Ada tiga rangkaian pengujian yang disertakan: pengujian unit, evaluasi, dan pengujian manual.

Pengujian unit dapat dijalankan menggunakan:

pnpm test

Evaluasi memerlukan file .env di root proyek dengan beberapa konfigurasi:

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

Catatan: File root .env menyediakan default untuk semua paket. Paket individual dapat memiliki file .env sendiri untuk mengganti default ini selama pengembangan.

Setelah itu selesai, Anda dapat menjalankannya menggunakan:

pnpm eval

Pengujian manual (lebih disukai untuk menguji perubahan 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"

Catatan: CLI default ke http://localhost:5173. Ganti dengan --mcp-host atau atur variabel lingkungan MCP_URL.

Panduan pengujian komprehensif:

• Pengujian Stdio: Lihat docs/testing/stdio.md untuk panduan lengkap tentang membangun, menjalankan, dan menguji implementasi stdio (IDE, Inspektur MCP)
• Pengujian jarak jauh: Lihat docs/testing/remote.md untuk panduan lengkap tentang menguji server jarak jauh (OAuth, UI web, klien CLI)

Catatan Pengembangan

Tinjauan Kode Otomatis

Repositori ini menggunakan alat tinjauan kode otomatis (seperti Cursor BugBot) untuk membantu mengidentifikasi potensi masalah dalam pull request. Alat-alat ini memberikan umpan balik dan saran yang membantu, tetapi kami tidak merekomendasikan menjadikan pemeriksaan ini wajib karena akurasinya masih berkembang dan dapat menghasilkan positif palsu.

Tinjauan otomatis harus diperlakukan sebagai:

• ✅ Saran yang membantu untuk dipertimbangkan selama tinjauan kode
• ✅ Titik awal untuk diskusi dan peningkatan
• ❌ Bukan persyaratan pemblokiran untuk menggabungkan PR
• ❌ Bukan pengganti untuk tinjauan kode manusia

Saat menangani umpan balik otomatis, fokuslah pada kekhawatiran mendasar daripada mengikuti setiap saran secara ketat.

Dokumentasi Kontributor

Ingin berkontribusi atau menjelajahi peta dokumentasi lengkap? Lihat CLAUDE.md (juga tersedia sebagai AGENTS.md) untuk alur kerja kontributor dan indeks dokumen lengkap. Folder docs/ berisi panduan per topik dan file .md yang terintegrasi alat.