sentry-mcp

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

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

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

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

https://mcp.sentry.dev

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

Claude Code Plugin

Установите как плагин 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 vs Remote

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

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

Чтобы использовать транспорт stdio, нужно создать в Sentry 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

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

Для изолированных внутренних развёртываний, которые expose только plain HTTP, также добавьте

--insecure-http.

Некоторые функции (например, Seer) могут быть недоступны на self-hosted инстансах. Вы можете

отключить конкретные навыки, чтобы предотвратить экспонирование неподдерживаемых инструментов:

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-заголовки, могут передать upstream Sentry API token напрямую в Cloudflare-транспорт:

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

Sentry-Bearer намеренно отделён от Bearer: Bearer зарезервирован для MCP OAuth access tokens. С Sentry-Bearer рабочий процесс не сохраняет, не валидирует, не обменивается и не обновляет upstream-токен. Он передаёт токен через те же вызовы Sentry API, которые используются сессиями, защищёнными OAuth, и клиент или upstream провайдер остаётся ответственным за срок действия токена и его обновление.

Прямой удалённый доступ по умолчанию включает все активные MCP навыки. При необходимости можно сузить доступные инструменты с помощью ?skills=inspect,triage или ?disable-skills=seer.

Переменные окружения

SENTRY_ACCESS_TOKEN=         # Обязательный: ваш токен аутентификации в Sentry

# Конфигурация провайдеров LLM (обязательно для инструментов поиска на базе ИИ)
EMBEDDED_AGENT_PROVIDER=     # Обязательно, когда заданы несколько ключей провайдера: 'openai', 'azure-openai', 'anthropic', или 'openrouter'
OPENAI_API_KEY=              # Обязательно при использовании OpenAI
ANTHROPIC_API_KEY=           # Обязательно при использовании Anthropic
OPENROUTER_API_KEY=          # Обязательно при использовании OpenRouter
OPENROUTER_MODEL=            # Необязательно, модель OpenRouter, по умолчанию 'openai/gpt-5'

# Необязательные переопределения
SENTRY_HOST=                 # Для self-hosted развёртываний
MCP_DISABLE_SKILLS=          # Отключение конкретных навыков (через запятую, напр. '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) и нажмите подключиться. Это должно запустить для вас процесс аутентификации.

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

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

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

Настройка окружения и навыков агентов:

make setup-env  # Создаёт .env-файлы и устанавливает общие навыки агентов

Это также запускает npx @sentry/dotagents install для установки общих навыков из getsentry/skills в .agents/skills/ (симлинк в .claude/skills и .cursor/skills). Если позже нужно будет обновить навыки, запустите это напрямую:

npx @sentry/dotagents install

Создание OAuth-приложения в Sentry (Settings => API => Applications):

Homepage URL: http://localhost:5173

Authorized Redirect URIs: http://localhost:5173/oauth/callback
Обратите внимание на ваш Client ID и сгенерируйте Client secret

Настройка учётных данных:

Отредактируйте .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

Запуск сервера разработки:

pnpm dev

Подтверждение

Запустите локально сервер, чтобы он стал доступен по адресу http://localhost:5173

pnpm dev

Чтобы протестировать локальный сервер, введите http://localhost:5173/mcp в Inspector и нажмите подключиться. После выполнения подсказок вы сможете увидеть пункт "List Tools".

Тесты

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

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

pnpm test

Оценки требуют файл .env в корне проекта с некоторыми настройками:

# .env (в корне проекта)
OPENAI_API_KEY=      # Используйте инструменты на базе OpenAI
OPENROUTER_API_KEY=  # Или используйте инструменты на базе OpenRouter

Примечание: корневой файл .env задаёт значения по умолчанию для всех пакетов. Отдельные пакеты могут иметь свои собственные .env файлы, чтобы переопределять эти значения во время разработки.

После этого можно запускать:

pnpm eval

Ручное тестирование (предпочтительно для проверки изменений MCP):

# Тест локального dev-сервера (по умолчанию: http://localhost:5173)
pnpm -w run cli "who am I?"

# Тест против продакшна
pnpm -w run cli --mcp-host=https://mcp.sentry.dev "query"

# Тест в локальном stdio-режиме (требуется 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)
Удалённое тестирование: см. docs/testing/remote.md для полного руководства по тестированию удалённого сервера (OAuth, веб-интерфейс, CLI-клиент)

Разработческие заметки

Автоматический обзор кода

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

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

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

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

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

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