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 (human-in-the-loop). 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 mọi chức năng của Sentry.

Máy chủ MCP từ xa này hoạt động như một lớp trung gian cho Sentry API phía trên, đượ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 trình 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ụ đã được 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 nó hoạt động, hoặc chạy dịch vụ này cho Sentry tự lưu trữ (self-hosted), hãy tiếp tục đọc bên dưới.

Plugin Claude Code

Cài đặt như một plugin Claude Code để tự động phân quyền cho subagent:

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

Plugin này cung cấp một subagent sentry-mcp mà Claude tự động phân quyền khi bạn hỏi về lỗi, issue, trace hoặc hiệu suất của Sentry.

Đối với các biến thể và tính năng công cụ 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ợ transport stdio. Đây vẫn là một công việc đang được phát triển, nhưng là cách dễ nhất để chạy MCP đối với một bản cài đặt Sentry tự lưu trữ.

Lưu ý: Các công cụ tìm kiếm hỗ trợ 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 để chuyển đổi 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 vẫn hoạt động bình thường.

Để sử dụng transport stdio, bạn cần tạo một User Auth Token trong Sentry với các phạm vi (scopes) cần thiết. Tính đến thời điểm viết tài liệu này, đó là:

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

Khởi chạy transport:

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

Cần kết nối đến một bản 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 bản triển khai nội bộ biệt lập chỉ phơi bày HTTP thuần, hãy 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ị phơi bày:

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ột Sentry Token tường minh

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ột Sentry API token phía trên đến transport 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ủ đích khỏi Bearer: Bearer được dành riêng cho các access token OAuth của MCP. Với Sentry-Bearer, worker không lưu trữ, xác thực, trao đổi hoặc làm mới token phía trên. Nó chuyển tiếp token qua các lệnh gọi Sentry API tương tự được sử dụng bởi các phiên hỗ trợ OAuth, và máy khách hoặc nhà cung cấp phía trên vẫn chịu trách nhiệm về vòng đời và việc làm mới token.

Xác thực từ xa trực tiếp mặc định áp dụng 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 phơi bày bằng ?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.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')

Quan trọng: Luôn đặt EMBEDDED_AGENT_PROVIDER để chỉ định tường minh nhà cung cấp LLM của bạn. Việc tự động phát hiện chỉ dựa trên các API key đã bị deprecated và sẽ bị loại bỏ trong một 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 để biến host không được đặt, CLI sẽ tự động nhắm đến dịch vụ Sentry SaaS. Chỉ đặt override 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. Thao tác 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 tại 127.0.0.1, hãy thử dùng localhost thay thế bằng cách truy cập http://localhost:6274.

Phát triển cục bộ (Local Development)

Để đóng góp thay đổi, bạn 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à các kỹ năng agent:

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

   Bước này cũng chạy npx @sentry/dotagents install để cài đặt các kỹ năng dùng chung 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 một OAuth App trong Sentry (Settings => API => Applications):

   • Homepage URL: http://localhost:5173
   • Authorized Redirect URIs: http://localhost:5173/oauth/callback
   • Ghi lại Client ID của bạn và tạo một Client secret

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ộ để 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 các bước hướng dẫn, bạn sẽ có thể "List Tools".

Kiểm thử (Tests)

Có ba bộ kiểm thử được bao gồm: unit tests, đánh giá (evaluations) và kiểm thử thủ công.

Unit tests có thể được chạy bằng:

pnpm test

Đánh giá (Evaluations) yêu cầu một tệp .env trong thư mục gốc của 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 ở thư mục gốc cung cấp các giá trị 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 giá trị 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:

pnpm eval

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

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.

Các sổ tay kiểm thử toàn diện:

• Kiểm thử Stdio: Xem docs/testing/stdio.md để biết hướng dẫn đầy đủ về việc 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 để biết hướng dẫn đầy đủ về việc 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 pull request. Các công cụ này cung cấp phản hồi và gợi ý hữu ích, nhưng chúng tôi không khuyến nghị yêu cầu 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 xem như:

• ✅ Các gợi ý hữu ích để cân nhắc 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 là yêu cầu chặn để hợp nhất PR
• ❌ Không thay thế cho việc đánh giá mã của con người

Khi xử lý 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 theo một cách cứng nhắc mọi gợi ý.

Tài liệu dành 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 hoàn chỉnh. Thư mục docs/ chứa các hướng dẫn theo từng chủ đề và các tệp .md tích hợp công cụ.