Sentry MCP

공식

공식 Sentry MCP 서버로, AI 코딩 에이전트의 이슈, 오류 보고서, 트레이스 및 성능 모니터링 데이터를 조사합니다.

GitHub
934

Sentry MCP(으)로 무엇을 할 수 있나요?

  • 오류 및 이슈 조사 — 어시스턴트에게 Sentry 오류 세부 정보, 스택 트레이스, 이슈 컨텍스트를 요청하여 디버깅하세요.
  • 성능 문제 추적 — 어시스턴트가 분산 트레이스와 성능 데이터를 분석하여 병목 지점을 정확히 찾아내도록 하세요.
  • 자연어로 검색 — AI 기반 검색을 사용하여 찾고자 하는 내용을 평문으로 설명함으로써 오류, 트레이스, 로그 또는 이슈를 조회하세요.
  • 프로젝트 분류 및 관리 — 어시스턴트에게 프로젝트 상태를 점검하고, 팀 할당을 검토하거나, 프로젝트 수준 구성을 처리하도록 요청하세요.
  • 자체 호스팅 Sentry 구성 — MCP 서버를 자체 Sentry 인스턴스에 연결하고 inspect 또는 seer 같은 스킬 활성화 여부를 조정하세요.

호스팅형 MCP 서버

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

Claude Code, Codex, Cursor 등에 설치됩니다

문서

Sentry 툴킷

이 저장소에는 Sentry CLI, Sentry MCP 서버 및 공유 패키지가 포함되어 있습니다. CLI에 대한 자세한 내용은 CLI 가이드 및 https://cli.sentry.dev/에 게시된 문서를 참조하세요. 문서 색인은 두 제품과 공유 기여자 가이드를 모두 다룹니다.

Sentry MCP

Sentry의 MCP 서비스는 주로 인간이 개입하는 코딩 에이전트를 위해 설계되었습니다. 도구 선택과 우선순위는 모든 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_errors, search_traces, search_logs, 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는 자체 호스팅 Sentry의 일부가 아니므로 --host이 비-sentry.io 호스트를 가리킬 때마다 seer 스킬은 기본 스킬 세트에서 제외됩니다. 자체 호스팅 배포에서 Seer를 실행하는 경우 명시적으로 다시 선택하세요:

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

지원되지 않는 도구가 노출되지 않도록 다른 스킬을 비활성화할 수도 있습니다:

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

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

중요: 항상 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를 운영할 때만 재정의를 설정하세요.

SENTRY_HOST를 자체 호스팅 호스트로 설정하면 Seer가 자체 호스팅 Sentry에서 사용할 수 없으므로 기본 세트에서 seer 스킬도 제거됩니다. Seer를 실행하는 자체 호스팅 배포의 경우 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에는 서비스를 쉽게 테스트할 수 있는 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 => 애플리케이션):

    • 홈페이지 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를 입력하고 연결을 누르세요. 프롬프트를 따라가면 "도구 나열"을 할 수 있습니다.

테스트

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

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

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 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)를 사용합니다. 이러한 도구는 유용한 피드백과 제안을 제공하지만 정확성이 아직 발전 중이고 오탐지를 생성할 수 있으므로 이러한 검사를 필수로 만들지 않는 것이 좋습니다.

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

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

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

기여자 문서

기여하고 싶으신가요? CLI, MCP 및 공유 가이드에 대한 툴킷 문서 색인에서 시작하세요. 저장소 규칙은 AGENTS.md를, CLI별 규칙은 packages/cli/AGENTS.md를 참조하세요.