Sentry MCP

sentry-mcp

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

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

시작하기

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

https://mcp.sentry.dev

기여를 원하거나, 작동 방식을 알아보거나, 자체 호스팅 Sentry용으로 실행하려면 아래 내용을 계속 확인하세요.

Claude Code 플러그인

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

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

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

미래 지향적인 도구 변형 및 기능을 확인하려면:

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

Stdio vs 원격

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

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

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

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)를 추가하세요. 일반 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

명시적 Sentry 토큰을 사용한 원격

사용자 지정 HTTP 헤더를 지원하는 원격 클라이언트는 업스트림 Sentry API 토큰을 Cloudflare 전송에 직접 전달할 수 있습니다:

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

Sentry-Bearer는 의도적으로 Bearer와 분리되어 있습니다: Bearer는 MCP OAuth 액세스 토큰용으로 예약되어 있습니다. Sentry-Bearer를 사용하면 워커는 업스트림 토큰을 저장, 검증, 교환 또는 갱신하지 않습니다. OAuth 기반 세션에서 사용되는 동일한 Sentry API 호출을 통해 토큰을 전달하며, 클라이언트 또는 업스트림 제공자가 토큰 수명 및 갱신에 대한 책임을 유지합니다.

직접 원격 인증은 기본적으로 모든 활성 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'

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

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

호스트 변수를 설정하지 않으면 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 인스펙터

MCP에는 서비스를 쉽게 테스트할 수 있는 인스펙터가 포함되어 있습니다:

pnpm inspector

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

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

로컬 개발

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

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

확인

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

pnpm dev

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

테스트

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

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

pnpm test

평가에는 프로젝트 루트에 일부 구성이 포함된 .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 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 인스펙터)을 빌드, 실행 및 테스트하는 전체 가이드는 docs/testing/stdio.md을 참조하세요.
• 원격 테스트: 원격 서버(OAuth, 웹 UI, CLI 클라이언트)를 테스트하는 전체 가이드는 docs/testing/remote.md을 참조하세요.

개발 노트

자동화된 코드 리뷰

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

자동화된 리뷰는 다음과 같이 취급해야 합니다:

• ✅ 코드 리뷰 중 고려할 유용한 제안
• ✅ 토론 및 개선을 위한 시작점
• ❌ PR 병합을 위한 차단 요구 사항이 아님
• ❌ 사람의 코드 리뷰를 대체하지 않음

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

기여자 문서

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