Sentry MCP

sentry-mcp

Layanan MCP Sentry dirancang terutama untuk agen pengkodean dengan manusia dalam loop (human-in-the-loop). Pemilihan alat dan prioritas kami berfokus pada alur kerja pengembang dan kasus penggunaan debugging, bukan menyediakan server MCP serba guna untuk semua fungsionalitas Sentry.

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

Memulai

Anda akan menemukan semua yang perlu Anda ketahui dengan mengunjungi layanan yang sudah di-deploy di produksi:

https://mcp.sentry.dev

Jika Anda ingin berkontribusi, mempelajari cara kerjanya, atau menjalankan ini untuk Sentry yang di-host sendiri (self-hosted), 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 error, issue, trace, atau performa Sentry.

Untuk varian alat dan fitur yang berorientasi ke depan:

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

Stdio vs Remote

Meskipun repositori ini berfokus pada peran sebagai layanan MCP, kami juga mendukung transport stdio. Ini masih dalam tahap pengembangan, tetapi merupakan cara termudah untuk mengadaptasi MCP agar berjalan terhadap instalasi Sentry yang di-host 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 khusus ini tidak akan tersedia, tetapi semua alat lainnya akan berfungsi normal.

Untuk memanfaatkan transport stdio, Anda perlu membuat User Auth Token di Sentry dengan scope yang diperlukan. Pada saat penulisan ini, scope tersebut 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 deployment yang di-host sendiri? Tambahkan --host (hanya nama host, misalnya --host=sentry.example.com) saat Anda menjalankan perintah. Untuk deployment internal terisolasi yang hanya mengekspos HTTP biasa, tambahkan juga --insecure-http.

Beberapa fitur (seperti Seer) mungkin tidak tersedia pada instance yang di-host sendiri. Anda dapat menonaktifkan skill tertentu untuk mencegah alat yang tidak didukung terekspos:

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

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 secara 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 me-refresh token upstream. Worker meneruskan token melalui panggilan API Sentry yang sama yang digunakan oleh sesi berbasis OAuth, dan klien atau penyedia upstream tetap bertanggung jawab atas masa berlaku dan refresh token.

Autentikasi remote langsung secara default mengaktifkan semua skill MCP yang 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
MCP_DISABLE_SKILLS=          # Disable specific skills (comma-separated, e.g. 'seer')

Penting: Selalu atur EMBEDDED_AGENT_PROVIDER untuk menentukan penyedia LLM Anda secara eksplisit. Deteksi otomatis berdasarkan kunci API saja sudah tidak digunakan lagi (deprecated) dan akan dihapus pada 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.

Untuk instance yang di-host 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"
      }
    }
  }
}

MCP Inspector

MCP menyertakan Inspector, untuk menguji layanan dengan mudah:

pnpm inspector

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

Catatan: Jika Anda mengalami masalah dengan alur OAuth saat mengakses inspector 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 skill agen:

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

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

   npx @sentry/dotagents install
   

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

   • URL Beranda: http://localhost:5173
   • URI Redirect yang Diotorisasi: http://localhost:5173/oauth/callback
   • Catat Client ID Anda dan buat Client secret

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 Inspector dan tekan connect. Setelah Anda mengikuti petunjuknya, Anda akan dapat "List Tools".

Pengujian

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

Unit test 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 di root menyediakan default untuk semua paket. Setiap paket 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 secara default menggunakan http://localhost:5173. Timpa dengan --mcp-host atau atur variabel lingkungan MCP_URL.

Buku panduan pengujian komprehensif:

• Pengujian Stdio: Lihat docs/testing/stdio.md untuk panduan lengkap tentang membangun, menjalankan, dan menguji implementasi stdio (IDE, MCP Inspector)
• Pengujian Remote: 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 pada pull request. Alat-alat ini memberikan umpan balik dan saran yang bermanfaat, tetapi kami tidak merekomendasikan menjadikan pemeriksaan ini sebagai keharusan karena akurasinya masih terus berkembang dan dapat menghasilkan positif palsu.

Tinjauan otomatis harus diperlakukan sebagai:

• ✅ Saran yang bermanfaat untuk dipertimbangkan selama tinjauan kode
• ✅ Titik awal untuk diskusi dan perbaikan
• ❌ Bukan persyaratan yang menghalangi untuk menggabungkan PR
• ❌ Bukan pengganti tinjauan kode oleh manusia

Saat menangani umpan balik otomatis, fokuslah pada kekhawatiran yang mendasarinya 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 dokumentasi lengkap. Folder docs/ berisi panduan per-topik dan file .md yang terintegrasi dengan alat.