Sentry MCP

sentry-mcp

Сервис MCP от Sentry в первую очередь предназначен для кодинг-агентов с участием человека в цикле (human-in-the-loop). Наш выбор инструментов и приоритеты ориентированы на рабочие процессы разработчиков и сценарии отладки, а не на предоставление универсального MCP-сервера для всего функционала Sentry.

Этот удалённый MCP-сервер действует как промежуточное звено (middleware) к вышестоящему Sentry API, оптимизирован для кодинг-ассистентов, таких как Cursor, Claude Code и аналогичных инструментов разработки. Он основан на работе Cloudflare над удалёнными MCP.

Начало работы

Всё, что вам нужно знать, вы найдёте, посетив развёрнутый сервис в продакшене:

https://mcp.sentry.dev

Если вы хотите внести вклад, узнать, как это работает, или запустить это для self-hosted Sentry, продолжайте читать ниже.

Плагин Claude Code

Установите как плагин Claude Code для автоматического делегирования субагентам:

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

Это предоставляет субагента sentry-mcp, которому Claude автоматически делегирует задачи, когда вы спрашиваете об ошибках Sentry, issue, трейсах или производительности.

Для перспективных вариантов инструментов и функций:

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

Stdio и Remote

Хотя этот репозиторий сосредоточен на работе в качестве MCP-сервиса, мы также поддерживаем транспорт stdio. Это всё ещё работа в процессе, но это самый простой способ адаптировать запуск MCP для self-hosted установки Sentry.

Примечание: Инструменты поиска на основе ИИ (search_events, search_issues и т.д.) требуют LLM-провайдера (OpenAI, Azure OpenAI, Anthropic или OpenRouter). Эти инструменты используют обработку естественного языка для преобразования запросов в синтаксис запросов Sentry. Без настроенного провайдера эти конкретные инструменты будут недоступны, но все остальные инструменты будут работать нормально.

Чтобы использовать транспорт stdio, вам нужно создать User Auth Token в Sentry с необходимыми правами (scopes). На момент написания это:

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

Запустите транспорт:

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

Нужно подключиться к self-hosted развёртыванию? Добавьте --host (только имя хоста, например, --host=sentry.example.com) при запуске команды. Для изолированных внутренних развёртываний, которые предоставляют только обычный HTTP, также добавьте --insecure-http.

Некоторые функции (например, Seer) могут быть недоступны на self-hosted экземплярах. Вы можете отключить отдельные навыки (skills), чтобы не раскрывать неподдерживаемые инструменты:

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

Для self-hosted экземпляров без TLS:

npx @sentry/mcp-server@latest --access-token=TOKEN --host=sentry.internal:9000 --insecure-http

Remote с явным токеном 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 воркер не хранит, не проверяет, не обменивает и не обновляет вышестоящий токен. Он передаёт токен через те же вызовы Sentry API, которые используются в сессиях на основе OAuth, и клиент или вышестоящий провайдер остаётся ответственным за время жизни и обновление токена.

Прямая удалённая аутентификация по умолчанию включает все активные навыки 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')

Важно: Всегда устанавливайте 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-..."
      }
    }
  }
}

Если вы оставите переменную host неустановленной, CLI автоматически нацеливается на сервис Sentry SaaS. Устанавливайте переопределение только тогда, когда вы работаете с self-hosted Sentry.

Для self-hosted экземпляров, не поддерживающих 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

Введите URL MCP-сервера (http://localhost:5173) и нажмите «connect». Это должно запустить процесс аутентификации за вас.

Примечание: Если у вас возникают проблемы с OAuth-потоком при доступе к Inspector на 127.0.0.1, попробуйте использовать localhost вместо этого, посетив http://localhost:6274.

Локальная разработка

Чтобы вносить изменения, вам нужно настроить локальное окружение:

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. Создайте OAuth-приложение в Sentry (Settings => API => Applications):

   • Homepage URL: http://localhost:5173
   • Authorized Redirect URIs: http://localhost:5173/oauth/callback
   • Запишите ваш Client ID и сгенерируйте Client secret

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 в Inspector и нажмите «connect». После того как вы пройдёте все шаги, вы сможете «List Tools».

Тесты

Включены три набора тестов: модульные тесты (unit tests), оценки (evaluations) и ручное тестирование.

Модульные тесты можно запустить с помощью:

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: См. docs/testing/stdio.md для полного руководства по сборке, запуску и тестированию реализации stdio (IDE, MCP Inspector)
• Тестирование Remote: См. docs/testing/remote.md для полного руководства по тестированию удалённого сервера (OAuth, веб-интерфейс, CLI-клиент)

Заметки по разработке

Автоматическое ревью кода

В этом репозитории используются инструменты автоматического ревью кода (например, Cursor BugBot) для выявления потенциальных проблем в pull request. Эти инструменты предоставляют полезные отзывы и предложения, но мы не рекомендуем делать эти проверки обязательными, поскольку точность всё ещё развивается и может давать ложные срабатывания.

Автоматические ревью следует рассматривать как:

• ✅ Полезные предложения, которые стоит учесть при ревью кода
• ✅ Отправные точки для обсуждения и улучшения
• ❌ Не блокирующие требования для слияния PR
• ❌ Не замену ревью человеком

При работе с автоматическими отзывами сосредоточьтесь на основных проблемах, а не строго следуйте каждому предложению.

Документация для контрибьюторов

Хотите внести вклад или изучить полную карту документации? См. CLAUDE.md (также доступно как AGENTS.md) для рабочих процессов контрибьюторов и полного индекса документации. Папка docs/ содержит руководства по каждой теме и интегрированные с инструментами файлы .md.