Sentry MCP

sentry-mcp

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

이 원격 MCP 서버는 업스트림 Sentry API에 대한 미들웨어 역할을 하며, Cursor, Claude Code 및 유사한 개발 도구와 같은 코딩 어시스턴트에 최적화되어 있습니다. 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

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

향후 지향적인 도구 변형 및 기능의 경우:

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

Stdio vs 원격

이 저장소는 MCP 서비스 역할에 초점을 맞추고 있지만, stdio 전송(transport)도 지원합니다. 이는 아직 진행 중인 작업이지만 자체 호스팅 Sentry 설치에 대해 MCP를 실행하는 가장 쉬운 방법입니다.

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

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

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

중요: LLM 제공자를 명시적으로 지정하려면 항상 EMBEDDED_AGENT_PROVIDER를 설정하세요. 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 Inspector

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

pnpm inspector

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

참고: 127.0.0.1에서 Inspector에 접근할 때 OAuth 흐름에 문제가 있으면 http://localhost:6274을 방문하여 localhost를 대신 사용해 보세요.

로컬 개발

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

1. 환경 및 에이전트 스킬 설정:

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

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

   npx @sentry/dotagents install
   

2. Sentry에서 OAuth 앱 생성 (설정 => API => Applications):

   • 홈페이지 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

로컬 서버를 테스트하려면 Inspector에 http://localhost:5173/mcp를 입력하고 연결을 누르세요. 프롬프트를 따라가면 "도구 나열(List Tools)"을 할 수 있습니다.

테스트

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

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

pnpm test

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

개발 노트

자동화된 코드 리뷰

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

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

• ✅ 코드 리뷰 중 고려할 유용한 제안
• ✅ 논의와 개선을 위한 출발점
• ❌ PR 병합을 차단하는 요구 사항이 아님
• ❌ 인간 코드 리뷰를 대체하지 않음

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

기여자 문서

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