Sentry MCP

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

Sentry Toolkit

Этот репозиторий содержит Sentry CLI, сервер Sentry MCP и общие пакеты. Для CLI см. руководство по CLI и опубликованную документацию по адресу https://cli.sentry.dev/. Индекс документации охватывает оба продукта и общие рекомендации для контрибьюторов.

Sentry MCP

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

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

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

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

Stdio против Remote

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

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

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

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 Sentry, поэтому навык seer исключен из набора навыков по умолчанию, когда --host указывает на хост, отличный от sentry.io. Если ваше self-hosted развертывание действительно запускает 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

Для 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 (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. Устанавливайте переопределение только при работе с self-hosted Sentry.

Установка SENTRY_HOST на self-hosted хост также удаляет навык seer из набора по умолчанию, поскольку Seer недоступен на self-hosted Sentry. Для self-hosted развертывания, которое действительно запускает 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

Введите 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 (Settings => API => Applications):

   • 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 и нажмите подключиться. После выполнения инструкций вы сможете "List Tools".

Тесты

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

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

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

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

Автоматизированное ревью кода

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

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

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

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

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

Хотите внести вклад? Начните с индекса документации Toolkit для руководств по CLI, MCP и общим темам. См. AGENTS.md для правил репозитория и packages/cli/AGENTS.md для правил, специфичных для CLI.