Sentry MCP

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

Bộ công cụ Sentry

Kho lưu trữ này chứa Sentry CLI, máy chủ Sentry MCP và các gói dùng chung. Để biết thông tin về CLI, hãy xem hướng dẫn CLI và tài liệu đã xuất bản tại https://cli.sentry.dev/. Chỉ mục tài liệu bao gồm cả hai sản phẩm và hướng dẫn đóng góp dùng chung.

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 trong vòng lặp. 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 dụng cho toàn bộ chức năng của Sentry.

Máy chủ MCP từ xa này hoạt động như phần mềm trung gian cho Sentry API thượng nguồ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ụ đã triển khai trong môi trường sản xuất:

https://mcp.sentry.dev

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

Plugin Claude Code

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ể 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ợ 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 hỗ trợ AI (search_errors, search_traces, search_logs, search_issues, v.v.) yêu cầu 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 truy vấn sang 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 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, đó 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 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ỉ hiển thị HTTP thuần túy, cũng thêm --insecure-http.

Seer không phải là một phần của Sentry tự lưu trữ, vì vậy kỹ năng seer bị loại khỏi bộ kỹ năng mặc định bất cứ khi nào --host trỏ đến một máy chủ không phải sentry.io. Nếu bản triển khai tự lưu trữ của bạn chạy Seer, hãy chọn tham gia lại một cách rõ ràng:

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

Bạn cũng có thể vô hiệu hóa bất kỳ kỹ năng nào khác để ngăn các công cụ không được hỗ trợ bị hiển thị:

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

Đố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 tường minh

Các máy khách từ xa hỗ trợ tiêu đề HTTP tùy chỉnh có thể truyền mã thông báo Sentry API thượng nguồn trực tiếp đế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ủ đích khỏi Bearer: Bearer được dành riêng cho mã thông báo truy cập OAuth MCP. 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 thượng nguồn. Nó chuyển tiếp mã thông báo 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 thượng nguồn vẫn chịu trách nhiệm về vòng đời 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ị 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 (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')

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 dựa trên khóa API đơn thuần đã không được dùng nữa 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ữ.

Việc đặt SENTRY_HOST thành máy chủ tự lưu trữ cũng loại bỏ kỹ năng seer khỏi bộ mặc định, vì Seer không khả dụng trên Sentry tự lưu trữ. Đối với bản triển khai tự lưu trữ chạy Seer, hãy chọn tham gia bằng 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"
      }
    }
  }
}

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

   Thao tá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/ (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 chú Client ID của bạn và tạo 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ộ để cung cấp 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 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ể chạy bằng:

pnpm test

Đánh giá yêu cầu 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 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 riê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 để 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 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 để biết hướng dẫn đầy đủ về xây dựng, chạy và kiểm tra triển khai stdio (IDE, MCP Inspector)
• Kiểm thử Remote: Xem docs/testing/remote.md để biết hướng dẫn đầy đủ về kiểm tra 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 xem như:

• ✅ Đề 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 phải sự thay thế cho đá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 nghiêm ngặt mọi đề xuất.

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

Muốn đóng góp? Bắt đầu tại Chỉ mục tài liệu Toolkit cho các hướng dẫn CLI, MCP và dùng chung. Xem AGENTS.md để biết các quy tắc kho lưu trữ và packages/cli/AGENTS.md cho các quy tắc cụ thể của CLI.