Sentry MCP

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

Sentry Toolkit

Repositori ini berisi Sentry CLI, server Sentry MCP, dan paket-paket bersama. Untuk CLI, lihat panduan CLI dan dokumentasi yang diterbitkan di https://cli.sentry.dev/. Indeks dokumentasi mencakup kedua produk dan panduan kontributor bersama.

Sentry MCP

Layanan MCP Sentry dirancang terutama untuk agen pengkodean dengan manusia dalam loop. Seleksi alat dan prioritas kami berfokus 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 upstream, 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 Anda ketahui dengan mengunjungi layanan yang diterapkan di produksi:

https://mcp.sentry.dev

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

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 error, masalah, jejak, atau kinerja Sentry.

Untuk varian alat dan fitur yang berorientasi masa depan:

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

Stdio vs Remote

Meskipun repositori ini berfokus pada bertindak sebagai layanan MCP, kami juga mendukung transport stdio. Ini masih dalam proses pengembangan, tetapi merupakan cara termudah untuk mengadaptasi menjalankan MCP terhadap instalasi Sentry yang di-host sendiri.

Catatan: Alat pencarian bertenaga AI (search_errors, search_traces, search_logs, 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 khusus ini tidak akan tersedia, tetapi semua alat lainnya akan berfungsi normal.

Untuk memanfaatkan transport stdio, Anda perlu membuat Token Auth Pengguna di Sentry dengan scope yang diperlukan. Pada saat penulisan ini adalah:

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 di-host 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.

Seer bukan bagian dari Sentry yang di-host sendiri, jadi keterampilan seer ditinggalkan dari set keterampilan default setiap kali --host menunjuk ke host non-sentry.io. Jika penerapan yang di-host sendiri Anda menjalankan Seer, pilih kembali secara eksplisit:

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

Anda juga dapat menonaktifkan keterampilan lain untuk mencegah alat yang tidak didukung diekspos:

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

Untuk instance yang di-host sendiri tanpa TLS:

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

Remote dengan Token Sentry Eksplisit

Klien jarak jauh yang mendukung header HTTP kustom dapat meneruskan token API Sentry upstream 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 upstream. Ini meneruskan token melalui panggilan API Sentry yang sama yang digunakan oleh sesi yang didukung OAuth, dan klien atau penyedia upstream tetap bertanggung jawab atas masa berlaku dan penyegaran token.

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

Penting: Selalu atur EMBEDDED_AGENT_PROVIDER untuk secara eksplisit menentukan penyedia LLM Anda. Deteksi otomatis berdasarkan kunci API saja sudah tidak digunakan lagi 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 diatur, CLI secara otomatis menargetkan layanan SaaS Sentry. Hanya atur override saat Anda mengoperasikan Sentry yang di-host sendiri.

Mengatur SENTRY_HOST ke host yang di-host sendiri juga menghapus keterampilan seer dari set default, karena Seer tidak tersedia di Sentry yang di-host sendiri. Untuk penerapan yang di-host sendiri yang menjalankan Seer, pilih dengan MCP_SKILLS:

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

Inspektur MCP

MCP menyertakan Inspektur, untuk menguji layanan dengan mudah:

pnpm inspector

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

Catatan: Jika Anda memiliki masalah dengan alur OAuth saat mengakses inspektur di 127.0.0.1, coba gunakan localhost sebagai gantinya 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 .agents/skills/ (ditautkan secara simbolis 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 yang Diotorisasi: http://localhost:5173/oauth/callback
   • Catat Client ID 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 untuk membuatnya 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 "Daftar Alat".

Tes

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

Tes 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 .env root menyediakan default untuk semua paket. Paket individual dapat memiliki file .env sendiri untuk menimpa default ini selama pengembangan.

Setelah 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 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. Timpa dengan --mcp-host atau atur variabel lingkungan MCP_URL.

Buku pedoman 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 permintaan tarik. 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 perbaikan
• ❌ Bukan persyaratan yang menghalangi untuk menggabungkan PR
• ❌ Bukan pengganti untuk tinjauan kode manusia

Saat menangani umpan balik otomatis, fokuslah pada masalah yang mendasarinya daripada mengikuti setiap saran secara ketat.

Dokumentasi Kontributor

Ingin berkontribusi? Mulailah di indeks dokumentasi Toolkit untuk panduan CLI, MCP, dan bersama. Lihat AGENTS.md untuk aturan repositori dan packages/cli/AGENTS.md untuk aturan khusus CLI.