Sentry MCP

sentry-mcp

บริการ MCP ของ Sentry ได้รับการออกแบบมาเป็นหลักสำหรับเอเจนต์การเขียนโค้ดแบบ human-in-the-loop (มีมนุษย์ร่วมวงจร) การเลือกเครื่องมือและลำดับความสำคัญของเรามุ่งเน้นไปที่ขั้นตอนการทำงานของนักพัฒนาและกรณีการใช้งานการดีบัก มากกว่าการให้บริการ MCP เซิร์ฟเวอร์เอนกประสงค์สำหรับฟังก์ชันทั้งหมดของ Sentry

เซิร์ฟเวอร์ MCP ระยะไกลนี้ทำหน้าที่เป็นมิดเดิลแวร์ไปยัง Sentry API ต้นทาง ซึ่งถูกปรับแต่งมาเพื่อผู้ช่วยเขียนโค้ดอย่าง Cursor, Claude Code และเครื่องมือพัฒนาที่คล้ายกัน มันสร้างจาก งานของ Cloudflare เกี่ยวกับ remote MCP

เริ่มต้นใช้งาน

คุณจะพบทุกสิ่งที่จำเป็นต้องรู้ได้จากการเข้าไปใช้บริการที่ deployed ในโปรดักชัน:

https://mcp.sentry.dev

หากคุณต้องการร่วมพัฒนาหรือเรียนรู้ว่ามันทำงานอย่างไร หรือต้องการรันสิ่งนี้สำหรับ Sentry ที่โฮสต์เอง (self-hosted) อ่านต่อด้านล่าง

Claude Code Plugin

ติดตั้งเป็นปลั๊กอิน Claude Code เพื่อการมอบหมายงานให้ซับเอเจนต์อัตโนมัติ:

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

สิ่งนี้ให้ซับเอเจนต์ sentry-mcp ที่ Claude มอบหมายงานให้โดยอัตโนมัติเมื่อคุณถามเกี่ยวกับข้อผิดพลาด, issues, traces หรือประสิทธิภาพของ Sentry

สำหรับตัวแปรและฟีเจอร์ของเครื่องมือที่มองไปข้างหน้า:

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

Stdio กับ Remote

แม้ repository นี้จะเน้นการทำหน้าที่เป็นบริการ MCP เราก็รองรับทรานสปอร์ต stdio ด้วย สิ่งนี้ยังอยู่ในระหว่างการพัฒนา แต่เป็นวิธีที่ง่ายที่สุดในการปรับใช้ MCP กับ Sentry ที่โฮสต์เอง (self-hosted)

หมายเหตุ: เครื่องมือค้นหาที่ขับเคลื่อนด้วย AI (search_events, search_issues, ฯลฯ) ต้องมีผู้ให้บริการ LLM (OpenAI, Azure OpenAI, Anthropic หรือ OpenRouter) เครื่องมือเหล่านี้ใช้การประมวลผลภาษาธรรมชาติเพื่อแปลงคำถามเป็นไวยากรณ์คำสั่งค้นหาของ Sentry หากไม่ได้ตั้งค่าผู้ให้บริการ เครื่องมือเฉพาะเหล่านี้จะไม่พร้อมใช้งาน แต่เครื่องมืออื่น ๆ ทั้งหมดจะทำงานได้ตามปกติ

หากต้องการใช้ทรานสปอร์ต stdio คุณจะต้องสร้าง User Auth Token ใน Sentry โดยมี scope ที่จำเป็น ซึ่งในขณะที่เขียนเอกสารนี้คือ:

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

เปิดใช้งานทรานสปอร์ต:

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

ต้องการเชื่อมต่อกับระบบที่โฮสต์เอง (self-hosted) หรือไม่? เพิ่ม --host (เฉพาะชื่อโฮสต์ เช่น --host=sentry.example.com) เมื่อคุณรันคำสั่ง สำหรับระบบภายในที่แยกออกมาและเปิดเผยเฉพาะ HTTP ธรรมดา ให้เพิ่ม --insecure-http ด้วย

ฟีเจอร์บางอย่าง (เช่น Seer) อาจไม่พร้อมใช้งานบนอินสแตนซ์ที่โฮสต์เอง คุณสามารถปิดใช้งานสกิลเฉพาะเพื่อไม่ให้เครื่องมือที่ไม่รองรับถูกเปิดเผย:

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

สำหรับอินสแตนซ์ที่โฮสต์เองโดยไม่มี TLS:

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

Remote พร้อม Sentry Token ที่ระบุอย่างชัดเจน

ไคลเอ็นต์ระยะไกลที่รองรับ HTTP headers แบบกำหนดเองสามารถส่ง Sentry API token ต้นทางไปยัง Cloudflare transport ได้โดยตรง:

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

Sentry-Bearer ถูกแยกจาก Bearer โดยตั้งใจ: Bearer สงวนไว้สำหรับ MCP OAuth access tokens ด้วย Sentry-Bearer ตัว worker จะไม่เก็บ ตรวจสอบ แลกเปลี่ยน หรือรีเฟรช token ต้นทาง มันจะส่งต่อ token ผ่านการเรียก Sentry API เดียวกันกับที่ใช้ในเซสชันที่ใช้ OAuth และไคลเอ็นต์หรือผู้ให้บริการต้นทางยังคงรับผิดชอบอายุและการรีเฟรช token

การรับรองความถูกต้องระยะไกลโดยตรง (direct remote auth) ค่าเริ่มต้นคือเปิดใช้สกิล MCP ทั้งหมดที่ใช้งานอยู่ คุณสามารถจำกัดเครื่องมือที่เปิดเผยได้ด้วย ?skills=inspect,triage หรือ ?disable-skills=seer

ตัวแปรสภาพแวดล้อม

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

สำคัญ: ตั้งค่า EMBEDDED_AGENT_PROVIDER เสมอเพื่อระบุผู้ให้บริการ LLM ของคุณอย่างชัดเจน การตรวจจับอัตโนมัติจาก API keys เพียงอย่างเดียวนั้นเลิกใช้งานแล้วและจะถูกลบออกในเวอร์ชันอนาคต ดู docs/operations/embedded-agents.md สำหรับตัวเลือกการกำหนดค่าโดยละเอียด

ตัวอย่างการกำหนดค่า MCP

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

หากคุณปล่อยตัวแปร host ไว้ไม่ตั้งค่า CLI จะกำหนดเป้าหมายไปที่บริการ Sentry SaaS โดยอัตโนมัติ ให้ตั้งค่า override เฉพาะเมื่อคุณใช้งาน Sentry ที่โฮสต์เองเท่านั้น

สำหรับอินสแตนซ์ที่โฮสต์เองที่ไม่รองรับ 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 มี Inspector สำหรับทดสอบบริการได้ง่าย ๆ:

pnpm inspector

ป้อน URL ของ MCP server (http://localhost:5173) แล้วกดเชื่อมต่อ สิ่งนี้ควรเริ่มขั้นตอนการรับรองความถูกต้องให้คุณ

หมายเหตุ: หากคุณมีปัญหากับ OAuth flow เมื่อเข้าถึง inspector บน 127.0.0.1 ให้ลองใช้ localhost แทนโดยไปที่ http://localhost:6274

การพัฒนาท้องถิ่น (Local Development)

หากต้องการร่วมแก้ไข คุณต้องเตรียมสภาพแวดล้อมท้องถิ่นของคุณ:

1. ตั้งค่าสภาพแวดล้อมและสกิลเอเจนต์:

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

   คำสั่งนี้ยังรัน npx @sentry/dotagents install เพื่อติดตั้งสกิลที่ใช้ร่วมกันจาก getsentry/skills ลงใน .agents/skills/ (symlinked ไปยัง .claude/skills และ .cursor/skills) หากคุณต้องการอัปเดตสกิลในภายหลัง ให้รันมันโดยตรง:

   npx @sentry/dotagents install
   

2. สร้าง OAuth App ใน Sentry (Settings => API => Applications):

   • Homepage URL: http://localhost:5173
   • Authorized Redirect URIs: http://localhost:5173/oauth/callback
   • จด Client ID ของคุณและสร้าง Client secret

3. กำหนดค่าข้อมูลประจำตัวของคุณ:

   • แก้ไข .env ในไดเรกทอรีรากและเพิ่ม OPENAI_API_KEY หรือ OPENROUTER_API_KEY
   • แก้ไข packages/mcp-cloudflare/.env และเพิ่ม:
     • SENTRY_CLIENT_ID=your_development_sentry_client_id
     • SENTRY_CLIENT_SECRET=your_development_sentry_client_secret
     • COOKIE_SECRET=my-super-secret-cookie

4. เริ่มเซิร์ฟเวอร์สำหรับการพัฒนา:

   pnpm dev
   

การตรวจสอบ (Verify)

รันเซิร์ฟเวอร์ในเครื่องเพื่อให้พร้อมใช้งานที่ http://localhost:5173

pnpm dev

หากต้องการทดสอบเซิร์ฟเวอร์ในเครื่อง ให้ป้อน http://localhost:5173/mcp ลงใน Inspector แล้วกดเชื่อมต่อ เมื่อคุณทำตามขั้นตอนแล้ว คุณจะสามารถ "List Tools" ได้

การทดสอบ (Tests)

มีชุดทดสอบสามชุด: unit tests, evaluations และการทดสอบด้วยตนเอง

Unit tests สามารถรันได้โดยใช้:

pnpm test

Evaluations ต้องมีไฟล์ .env ในรากของโปรเจกต์พร้อมค่ากำหนดบางอย่าง:

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

หมายเหตุ: ไฟล์ .env ที่รากมีค่าเริ่มต้นสำหรับทุกแพ็กเกจ แต่ละแพ็กเกจสามารถมีไฟล์ .env ของตัวเองเพื่อแทนที่ค่าเริ่มต้นเหล่านี้ระหว่างการพัฒนา

เมื่อเสร็จแล้วคุณสามารถรันได้โดยใช้:

pnpm eval

การทดสอบด้วยตนเอง (ที่ต้องการสำหรับการทดสอบการเปลี่ยนแปลง 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"

หมายเหตุ: CLI ใช้ค่าเริ่มต้นเป็น http://localhost:5173 แทนที่ด้วย --mcp-host หรือตั้งค่าตัวแปรสภาพแวดล้อม MCP_URL

Playbooks การทดสอบที่ครอบคลุม:

• การทดสอบ Stdio: ดู docs/testing/stdio.md สำหรับคำแนะนำฉบับสมบูรณ์เกี่ยวกับการ build, รัน และทดสอบการใช้งาน stdio (IDEs, MCP Inspector)
• การทดสอบระยะไกล: ดู docs/testing/remote.md สำหรับคำแนะนำฉบับสมบูรณ์เกี่ยวกับการทดสอบเซิร์ฟเวอร์ระยะไกล (OAuth, web UI, CLI client)

หมายเหตุการพัฒนา

การตรวจสอบโค้ดอัตโนมัติ

Repository นี้ใช้เครื่องมือตรวจสอบโค้ดอัตโนมัติ (เช่น Cursor BugBot) เพื่อช่วยระบุปัญหาที่อาจเกิดขึ้นใน pull requests เครื่องมือเหล่านี้ให้ข้อเสนอแนะและคำแนะนำที่เป็นประโยชน์ แต่ เราไม่แนะนำให้กำหนดให้การตรวจสอบเหล่านี้เป็นข้อบังคับ เนื่องจากความแม่นยำยังคงพัฒนาไปเรื่อย ๆ และอาจสร้างผลบวกลวง (false positives) ได้

การตรวจสอบอัตโนมัติควรถือเป็น:

• ✅ คำแนะนำที่เป็นประโยชน์ ที่ควรพิจารณาระหว่างการตรวจสอบโค้ด
• ✅ จุดเริ่มต้น สำหรับการอภิปรายและการปรับปรุง
• ❌ ไม่ใช่ข้อกำหนดที่บล็อก การรวม PR
• ❌ ไม่ใช่สิ่งทดแทน การตรวจสอบโค้ดโดยมนุษย์

เมื่อจัดการกับข้อเสนอแนะอัตโนมัติ ให้มุ่งเน้นที่ข้อกังวลพื้นฐานมากกว่าการทำตามทุกคำแนะนำอย่างเคร่งครัด

เอกสารสำหรับผู้ร่วมพัฒนา

ต้องการร่วมพัฒนาหรือสำรวจแผนที่เอกสารฉบับเต็มหรือไม่? ดู CLAUDE.md (มีเป็น AGENTS.md ด้วย) สำหรับขั้นตอนการทำงานของผู้ร่วมพัฒนาและดัชนีเอกสารฉบับสมบูรณ์ โฟลเดอร์ docs/ มีคำแนะนำรายหัวข้อและไฟล์ .md ที่ผสานรวมกับเครื่องมือ