sentry-mcp

Sentry의 MCP 서비스는 주로 인간이 개입하는(human-in-the-loop) 코딩 에이전트를 위해 설계되었습니다. 도구 선택과 우선순위는 모든 Sentry 기능을 위한 범용 MCP 서버를 제공하는 것이 아니라, 개발자 워크플로우와 디버깅 사용 사례에 초점을 맞추고 있습니다.

이 원격 MCP 서버는 Cursor, Claude Code 및 유사한 개발 도구와 같은 코딩 어시스턴트에 최적화된 업스트림 Sentry API의 미들웨어 역할을 합니다. 이 서버는 Cloudflare의 원격 MCP를 향한 노력을 기반으로 합니다.

시작하기

프로덕션에 배포된 서비스에 방문하면 필요한 모든 정보를 확인할 수 있습니다:

https://mcp.sentry.dev

기여 방법, 작동 원리 또는 자체 호스팅 Sentry에서 실행하는 방법을 알아보려면 아래 내용을 계속 확인하세요.

Claude Code 플러그인

자동 하위 에이전트 위임을 위해 Claude Code 플러그인으로 설치하세요:

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

이는 Claude가 Sentry 오류, 이슈, 추적 또는 성능에 대해 질문할 때 자동으로 위임하는 sentry-mcp 하위 에이전트를 제공합니다.

향후 도구 변형 및 기능을 보려면:

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

Stdio vs 원격

이 저장소는 MCP 서비스 역할에 중점을 두고 있지만, stdio 전송도 지원합니다. 이는 아직 작업 중이지만, 자체 호스팅 Sentry 설치 환경에서 MCP를 실행하도록 조정하는 가장 쉬운 방법입니다.

참고: AI 기반 검색 도구(search_events, search_issues 등)는 LLM 공급자(OpenAI 또는 Anthropic)가 필요합니다. 이러한 도구는 자연어 처리를 사용하여 쿼리를 Sentry의 쿼리 구문으로 변환합니다. 구성된 공급자가 없으면 이러한 특정 도구는 사용할 수 없지만, 다른 모든 도구는 정상적으로 작동합니다.

stdio 전송을 사용하려면 Sentry에서 필요한 범위(scope)를 가진 사용자 인증 토큰을 생성해야 합니다. 작성 시점 기준으로 범위는 다음과 같습니다:

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

전송 시작:

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

자체 호스팅 배포에 연결해야 하나요? 명령을 실행할 때 --host(호스트 이름만, 예: --host=sentry.example.com)를 추가하세요.

일부 기능(예: Seer)은 자체 호스팅 인스턴스에서 사용하지 못할 수 있습니다. 지원되지 않는 도구가 노출되지 않도록 특정 기술을 비활성화할 수 있습니다:

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

환경 변수

SENTRY_ACCESS_TOKEN= # Required: Your Sentry auth token

# LLM Provider Configuration (required for AI-powered search tools)
EMBEDDED_AGENT_PROVIDER= # Required: 'openai' or 'anthropic'
OPENAI_API_KEY= # Required if using OpenAI
ANTHROPIC_API_KEY= # Required if using Anthropic

# Optional overrides
SENTRY_HOST= # For self-hosted deployments
MCP_DISABLE_SKILLS= # Disable specific skills (comma-separated, e.g. 'seer')

중요: LLM 공급자를 명시적으로 지정하려면 항상 EMBEDDED_AGENT_PROVIDER를 설정하세요. API 키만 기반으로 하는 자동 감지는 더 이상 사용되지 않으며 향후 릴리스에서 제거될 예정입니다. 자세한 구성 옵션은 docs/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-..."
 }
 }
 }
}

호스트 변수를 설정하지 않으면 CLI는 자동으로 Sentry SaaS 서비스를 대상으로 합니다. 자체 호스팅 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

MCP 서버 URL(http://localhost:5173)을 입력하고 연결을 누르세요. 그러면 인증 흐름이 트리거됩니다.

참고: 127.0.0.1에서 인스펙터에 액세스할 때 OAuth 흐름에 문제가 있는 경우, http://localhost:6274를 방문하여 localhost를 대신 사용해 보세요.

Related MCP server: Sentry MCP Server

로컬 개발

변경 사항을 기여하려면 로컬 환경을 설정해야 합니다:

1. 환경 및 에이전트 기술 설정:

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

   또한 npx @sentry/dotagents install을 실행하여 getsentry/skills의 공유 기술을 .agents/skills/에 설치합니다(.claude/skills 및 .cursor/skills로 심볼릭 링크됨). 나중에 기술을 업데이트해야 하는 경우 직접 실행하세요:

   npx @sentry/dotagents install

2. Sentry에서 OAuth 앱 생성 (설정 => API => 애플리케이션):

   • 홈페이지 URL: http://localhost:5173

   • 승인된 리디렉션 URI: http://localhost:5173/oauth/callback

   • 클라이언트 ID를 기록하고 클라이언트 시크릿을 생성하세요.

3. 자격 증명 구성:

   • 루트 디렉토리의 .env를 편집하고 OPENAI_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

확인

서버를 로컬에서 실행하여 http://localhost:5173에서 사용할 수 있도록 합니다.

pnpm dev

로컬 서버를 테스트하려면 인스펙터에 http://localhost:5173/mcp를 입력하고 연결을 누르세요. 프롬프트를 따르면 "List Tools"를 수행할 수 있습니다.

테스트

단위 테스트, 평가, 수동 테스트의 세 가지 테스트 제품군이 포함되어 있습니다.

단위 테스트는 다음을 사용하여 실행할 수 있습니다:

pnpm test

평가를 위해서는 프로젝트 루트에 일부 구성이 포함된 .env 파일이 필요합니다:

# .env (in project root)
OPENAI_API_KEY= # Also required for AI-powered search tools in production

참고: 루트 .env 파일은 모든 패키지에 대한 기본값을 제공합니다. 개별 패키지는 개발 중에 이러한 기본값을 재정의하기 위해 자체 .env 파일을 가질 수 있습니다.

완료되면 다음을 사용하여 실행할 수 있습니다:

pnpm eval

수동 테스트(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"

참고: CLI는 기본적으로 http://localhost:5173을 사용합니다. --mcp-host로 재정의하거나 MCP_URL 환경 변수를 설정하세요.

포괄적인 테스트 플레이북:

• Stdio 테스트: stdio 구현(IDE, MCP Inspector)을 빌드, 실행 및 테스트하는 전체 가이드는 docs/testing-stdio.md를 참조하세요.

• 원격 테스트: 원격 서버(OAuth, 웹 UI, CLI 클라이언트)를 테스트하는 전체 가이드는 docs/testing-remote.md를 참조하세요.

개발 참고 사항

자동 코드 리뷰

이 저장소는 풀 리퀘스트에서 잠재적인 문제를 식별하는 데 도움이 되도록 자동 코드 리뷰 도구(예: Cursor BugBot)를 사용합니다. 이러한 도구는 유용한 피드백과 제안을 제공하지만, 정확도가 계속 발전 중이며 오탐(false positive)이 발생할 수 있으므로 이러한 검사를 필수로 설정하는 것은 권장하지 않습니다.

자동 리뷰는 다음과 같이 처리해야 합니다:

• ✅ 코드 리뷰 중에 고려할 유용한 제안

• ✅ 토론 및 개선을 위한 시작점

• ❌ PR 병합을 위한 차단 요구 사항 아님

• ❌ 인간 코드 리뷰의 대체재 아님

자동화된 피드백을 처리할 때는 모든 제안을 엄격하게 따르기보다 근본적인 우려 사항에 집중하세요.

기여자 문서

기여하거나 전체 문서 맵을 탐색하고 싶으신가요? 기여자 워크플로우 및 전체 문서 색인은 CLAUDE.md(AGENTS.md로도 제공)를 참조하세요. docs/ 폴더에는 주제별 가이드와 도구 통합 .md 파일이 포함되어 있습니다.

Maintenance

Resources

• NPM Package
• GitHub Repository
Need Help?Related Servers

Tools

• create_projectB
• create_teamB
• get_error_detailsA
• list_organizationsB
• list_projectsB
• list_teamsA
• search_errors_in_fileA