Sentry MCP

sentry-mcp

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

Этот удаленный MCP-сервер выступает в роли промежуточного слоя для вышестоящего API Sentry, оптимизированного для ассистентов кодирования, таких как 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-mcp, которому Claude автоматически делегирует задачи, когда вы спрашиваете об ошибках, проблемах, трассировках или производительности Sentry.

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

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

Stdio против Remote

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

Примечание: Инструменты поиска на базе ИИ (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-заголовки, могут передавать вышестоящий токен API Sentry напрямую в транспорт Cloudflare:

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

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

# 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 Inspector

MCP включает Inspector для удобного тестирования сервиса:

pnpm inspector

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

Примечание: Если у вас возникли проблемы с потоком OAuth при доступе к инспектору на 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 (Настройки => API => Приложения):

   • URL домашней страницы: http://localhost:5173
   • Разрешенные URI перенаправления: 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 и нажмите «Подключиться». После выполнения инструкций вы сможете «Показать список инструментов».

Тесты

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

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

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

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

Автоматизированная проверка кода

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

Автоматизированные проверки следует рассматривать как:

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

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

Документация для участников

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