Sentry MCP

sentry-mcp

Dịch vụ MCP của Sentry được thiết kế chủ yếu cho các tác nhân lập trình có sự tham gia của con người. Việc lựa chọn công cụ và ưu tiên của chúng tôi tập trung vào quy trình làm việc của nhà phát triển và các trường hợp sử dụng gỡ lỗi, thay vì cung cấp một máy chủ MCP đa năng cho tất cả chức năng của Sentry.

Máy chủ MCP từ xa này hoạt động như một middleware cho API ngược dòng của Sentry, được tối ưu hóa cho các trợ lý lập trình như Cursor, Claude Code và các công cụ phát triển tương tự. Nó dựa trên công việc của Cloudflare hướng tới MCP từ xa.

Bắt đầu

Bạn sẽ tìm thấy mọi thứ cần biết bằng cách truy cập dịch vụ đã triển khai trong môi trường production:

https://mcp.sentry.dev

Nếu bạn muốn đóng góp, tìm hiểu cách thức hoạt động hoặc chạy dịch vụ này cho Sentry tự lưu trữ, hãy tiếp tục đọc bên dưới.

Claude Code Plugin

Cài đặt dưới dạng plugin Claude Code để tự động ủy quyền cho tác nhân phụ:

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

Điều này cung cấp một tác nhân phụ sentry-mcp mà Claude tự động ủy quyền khi bạn hỏi về lỗi, sự cố, dấu vết hoặc hiệu suất của Sentry.

Đối với các biến thể công cụ và tính năng hướng tới tương lai:

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

Stdio so với Remote

Mặc dù kho lưu trữ này tập trung vào việc hoạt động như một dịch vụ MCP, chúng tôi cũng hỗ trợ truyền tải stdio. Đây vẫn là một công việc đang được tiến hành, nhưng là cách dễ nhất để điều chỉnh chạy MCP với bản cài đặt Sentry tự lưu trữ.

Lưu ý: Các công cụ tìm kiếm được hỗ trợ bởi AI (search_events, search_issues, v.v.) yêu cầu một nhà cung cấp LLM (OpenAI, Azure OpenAI, Anthropic hoặc OpenRouter). Các công cụ này sử dụng xử lý ngôn ngữ tự nhiên để dịch các truy vấn thành cú pháp truy vấn của Sentry. Nếu không có nhà cung cấp được cấu hình, các công cụ cụ thể này sẽ không khả dụng, nhưng tất cả các công cụ khác sẽ hoạt động bình thường.

Để sử dụng truyền tải stdio, bạn sẽ cần tạo Mã thông báo Xác thực Người dùng trong Sentry với các phạm vi cần thiết. Tại thời điểm viết bài này là:

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

Khởi chạy truyền tải:

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

Cần kết nối với triển khai tự lưu trữ? Thêm --host (chỉ tên máy chủ, ví dụ: --host=sentry.example.com) khi bạn chạy lệnh. Đối với các triển khai nội bộ biệt lập chỉ hiển thị HTTP thuần túy, cũng thêm --insecure-http.

Một số tính năng (như Seer) có thể không khả dụng trên các phiên bản tự lưu trữ. Bạn có thể vô hiệu hóa các kỹ năng cụ thể để ngăn các công cụ không được hỗ trợ bị lộ ra:

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

Đối với các phiên bản tự lưu trữ không có TLS:

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

Remote với Mã thông báo Sentry Rõ ràng

Các máy khách từ xa hỗ trợ tiêu đề HTTP tùy chỉnh có thể truyền trực tiếp mã thông báo API ngược dòng của Sentry đến truyền tải Cloudflare:

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

Sentry-Bearer được tách biệt có chủ ý khỏi Bearer: Bearer được dành riêng cho mã thông báo truy cập MCP OAuth. Với Sentry-Bearer, worker không lưu trữ, xác thực, trao đổi hoặc làm mới mã thông báo ngược dòng. Nó chuyển tiếp mã thông báo qua cùng các lệnh gọi API Sentry được sử dụng bởi các phiên được hỗ trợ bởi OAuth, và máy khách hoặc nhà cung cấp ngược dòng vẫn chịu trách nhiệm về thời hạn và làm mới mã thông báo.

Xác thực từ xa trực tiếp mặc định cho tất cả các kỹ năng MCP đang hoạt động. Bạn có thể thu hẹp các công cụ được hiển thị với ?skills=inspect,triage hoặc ?disable-skills=seer.

Biến Môi trường

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

Quan trọng: Luôn đặt EMBEDDED_AGENT_PROVIDER để chỉ định rõ ràng nhà cung cấp LLM của bạn. Tự động phát hiện chỉ dựa trên khóa API đã bị phản đối và sẽ bị xóa trong bản phát hành tương lai. Xem docs/operations/embedded-agents.md để biết các tùy chọn cấu hình chi tiết.

Ví dụ Cấu hình MCP

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

Nếu bạn để trống biến máy chủ, CLI sẽ tự động nhắm mục tiêu dịch vụ Sentry SaaS. Chỉ đặt ghi đè khi bạn vận hành Sentry tự lưu trữ.

Đối với các phiên bản tự lưu trữ không hỗ trợ 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 bao gồm một Inspector, để dễ dàng kiểm tra dịch vụ:

pnpm inspector

Nhập URL máy chủ MCP (http://localhost:5173) và nhấn kết nối. Điều này sẽ kích hoạt luồng xác thực cho bạn.

Lưu ý: Nếu bạn gặp sự cố với luồng OAuth khi truy cập inspector trên 127.0.0.1, hãy thử sử dụng localhost thay thế bằng cách truy cập http://localhost:6274.

Phát triển Cục bộ

Để đóng góp thay đổi, bạn sẽ cần thiết lập môi trường cục bộ của mình:

1. Thiết lập môi trường và kỹ năng tác nhân:

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

   Điều này cũng chạy npx @sentry/dotagents install để cài đặt các kỹ năng được chia sẻ từ getsentry/skills vào .agents/skills/ (được liên kết tượng trưng vào .claude/skills và .cursor/skills). Nếu bạn cần cập nhật kỹ năng sau này, hãy chạy trực tiếp:

   npx @sentry/dotagents install
   

2. Tạo Ứng dụng OAuth trong Sentry (Cài đặt => API => Ứng dụng):

   • URL Trang chủ: http://localhost:5173
   • URI Chuyển hướng được Ủy quyền: http://localhost:5173/oauth/callback
   • Ghi lại ID Khách hàng của bạn và tạo Bí mật Khách hàng

3. Cấu hình thông tin xác thực của bạn:

   • Chỉnh sửa .env trong thư mục gốc và thêm OPENAI_API_KEY hoặc OPENROUTER_API_KEY
   • Chỉnh sửa packages/mcp-cloudflare/.env và thêm:
     • SENTRY_CLIENT_ID=your_development_sentry_client_id
     • SENTRY_CLIENT_SECRET=your_development_sentry_client_secret
     • COOKIE_SECRET=my-super-secret-cookie

4. Khởi động máy chủ phát triển:

   pnpm dev
   

Xác minh

Chạy máy chủ cục bộ để làm cho nó khả dụng tại http://localhost:5173

pnpm dev

Để kiểm tra máy chủ cục bộ, nhập http://localhost:5173/mcp vào Inspector và nhấn kết nối. Sau khi bạn làm theo lời nhắc, bạn sẽ có thể "Liệt kê Công cụ".

Kiểm thử

Có ba bộ kiểm thử được bao gồm: kiểm thử đơn vị, đánh giá và kiểm thử thủ công.

Kiểm thử đơn vị có thể được chạy bằng cách sử dụng:

pnpm test

Đánh giá yêu cầu một tệp .env trong thư mục gốc dự án với một số cấu hình:

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

Lưu ý: Tệp .env gốc cung cấp mặc định cho tất cả các gói. Các gói riêng lẻ có thể có tệp .env của riêng chúng để ghi đè các mặc định này trong quá trình phát triển.

Sau khi hoàn tất, bạn có thể chạy chúng bằng cách sử dụng:

pnpm eval

Kiểm thử thủ công (được ưu tiên để kiểm tra các thay đổi 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"

Lưu ý: CLI mặc định là http://localhost:5173. Ghi đè bằng --mcp-host hoặc đặt biến môi trường MCP_URL.

Sổ tay kiểm thử toàn diện:

• Kiểm thử Stdio: Xem docs/testing/stdio.md để có hướng dẫn đầy đủ về xây dựng, chạy và kiểm thử triển khai stdio (IDE, MCP Inspector)
• Kiểm thử từ xa: Xem docs/testing/remote.md để có hướng dẫn đầy đủ về kiểm thử máy chủ từ xa (OAuth, giao diện web, máy khách CLI)

Ghi chú Phát triển

Đánh giá Mã Tự động

Kho lưu trữ này sử dụng các công cụ đánh giá mã tự động (như Cursor BugBot) để giúp xác định các vấn đề tiềm ẩn trong các yêu cầu kéo. Các công cụ này cung cấp phản hồi và đề xuất hữu ích, nhưng chúng tôi không khuyến nghị bắt buộc các kiểm tra này vì độ chính xác vẫn đang phát triển và có thể tạo ra kết quả dương tính giả.

Các đánh giá tự động nên được coi là:

• ✅ Đề xuất hữu ích để xem xét trong quá trình đánh giá mã
• ✅ Điểm khởi đầu cho thảo luận và cải tiến
• ❌ Không phải yêu cầu chặn để hợp nhất PR
• ❌ Không thay thế cho đánh giá mã của con người

Khi giải quyết phản hồi tự động, hãy tập trung vào các mối quan tâm cơ bản thay vì tuân thủ nghiêm ngặt mọi đề xuất.

Tài liệu cho Người đóng góp

Muốn đóng góp hoặc khám phá bản đồ tài liệu đầy đủ? Xem CLAUDE.md (cũng có sẵn dưới dạng AGENTS.md) để biết quy trình làm việc của người đóng góp và chỉ mục tài liệu đầy đủ. Thư mục docs/ chứa các hướng dẫn theo chủ đề và các tệp .md được tích hợp công cụ.