GrowthBook

GrowthBook MCP Thin

Тонкий MCP-сервер для GrowthBook с четырьмя инструментами:

Инструмент	Назначение
growthbook_list_skills	Список точек входа в навыки верхнего уровня (имя + описание)
growthbook_read_skill	Возврат указанного навыка или квалифицированного дочернего рабочего процесса (feature-flags или feature-flags/references/flag-create)
growthbook_api_read	Аутентифицированный GET-прокси к API GrowthBook
growthbook_api_write	Аутентифицированный POST/PUT/PATCH/DELETE-прокси

Компетенции находятся в репозитории навыков и встраиваются во время сборки. Возможности разделены на инструменты чтения и записи API (без форматтеров для отдельных конечных точек), чтобы клиенты могли корректно обрабатывать readOnlyHint / destructiveHint.

Инструменты имеют префикс growthbook_, чтобы оставаться однозначными, когда у клиента загружено несколько MCP-серверов.

Плагин Cursor

Установите GrowthBook из Cursor Marketplace. Плагин подключает Cursor к размещенному серверу по адресу https://mcp.growthbook.io/mcp; первый вызов инструмента открывает вход в GrowthBook для авторизации. Пользователям самостоятельно размещенного GrowthBook следует настроить сервер вручную, как описано ниже.

Плагин определяется через .cursor-plugin/plugin.json и mcp.json. Чтобы протестировать изменения локально, скопируйте репозиторий в ~/.cursor/plugins/local/growthbook и выполните Developer: Reload Window.

Установка / запуск

npm install
npm run build

Укажите вашему MCP-клиенту скомпилированную точку входа:

{
  "mcpServers": {
    "growthbook": {
      "command": "node",
      "args": ["/absolute/path/to/growthbook-mcp/server/index.js"],
      "env": {
        "GB_API_KEY": "your_api_key_or_pat",
        "GB_API_URL": "https://api.growthbook.io"
      }
    }
  }
}

Или запустите опубликованный пакет:

npx @growthbook/mcp

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

Переменная	Обязательная	По умолчанию	Назначение
GB_API_KEY	Да для stdio; необязательно для HTTP OAuth	—	Ключ API GrowthBook или персональный токен доступа
GB_API_URL	Нет	https://api.growthbook.io	Базовый URL API (самостоятельное размещение) и издатель AS по умолчанию для OAuth
GB_MCP_TRANSPORT	Нет	stdio	stdio или http
GB_MCP_PORT	Нет	3333	Порт прослушивания HTTP (когда transport=http)
GB_MCP_HOST	Нет	127.0.0.1	Хост привязки HTTP
GB_MCP_URL	Да для HTTP	—	Публичный базовый URL MCP, встраиваемый в метаданные ресурса OAuth (сервер отказывается запускаться в HTTP-режиме без него)
GB_MCP_KEEP_ALIVE_TIMEOUT_MS	Нет	90000	Тайм-аут простоя keep-alive в HTTP-режиме. Должен превышать тайм-аут простоя любого балансировщика нагрузки перед сервером, иначе LB может повторно использовать соединение, которое сервер уже закрыл, и запрос завершится ошибкой 502
OPENAI_APPS_CHALLENGE_TOKEN	Нет	—	Обслуживается как обычный текст по адресу /.well-known/openai-apps-challenge для проверки домена плагина OpenAI (HTTP-режим); маршрут возвращает 404, если не задано
GB_OAUTH_ISSUER	Нет	GB_API_URL	URL издателя AS OAuth GrowthBook
GB_HTTP_HEADER_*	Нет	—	Дополнительные заголовки запросов (например, GB_HTTP_HEADER_CF_ACCESS_TOKEN)
GB_SKILLS_ENABLED	Нет	true	Установите в false / 0, чтобы отключить инструменты навыков

Режим HTTP + OAuth

OAUTH_AS_ENABLED=1  # on the GrowthBook API
GB_MCP_TRANSPORT=http GB_API_URL=http://localhost:3100 GB_MCP_PORT=3333 npm start

Клиенты подключаются к:

• http://127.0.0.1:3333/mcp — полный (навыки + чтение/запись API)
• http://127.0.0.1:3333/mcp/api — только возможности (growthbook_api_read + growthbook_api_write)

Неаутентифицированные запросы получают 401 с WWW-Authenticate, указывающим на /.well-known/oauth-protected-resource, который рекламирует сервер авторизации GrowthBook.

Перед обработкой MCP сервер проверяет REST GrowthBook (GET /api/v1/) с помощью bearer-токена. 401 от этой проверки (или позже от инструмента API) приводит к HTTP 401 с error="invalid_token", чтобы MCP-клиент мог обновить токен — вместо отображения "This API key has expired" как ошибки инструмента. 403 рассматривается как принятый bearer-токен (отказ в разрешении ≠ недействительный токен), чтобы клиенты не попадали в цикл обновления.

Режим только возможностей

HTTP (рекомендуется для удаленного доступа): укажите клиенту /mcp/api вместо /mcp:

{
  "mcpServers": {
    "growthbook": {
      "url": "http://127.0.0.1:3333/mcp/api"
    }
  }
}

Путь	Инструменты
/mcp	growthbook_list_skills, growthbook_read_skill, growthbook_api_read, growthbook_api_write (если не GB_SKILLS_ENABLED=false)
/mcp/api	growthbook_api_read, growthbook_api_write только

stdio / для всего процесса: установите переменные окружения, чтобы навыки никогда не регистрировались:

"env": {
  "GB_API_KEY": "...",
  "GB_SKILLS_ENABLED": "false"
}

Когда навыки отключены, регистрируются только инструменты чтения/записи API. growthbook_list_skills и growthbook_read_skill не предоставляются.

Как встраиваются навыки

npm run build   # tsc && bundle-skills

scripts/bundle-skills.mjs копирует дерево навыков верхнего уровня из канонического репозитория навыков, сохраняя структуру:

skills/<skill>/SKILL.md                   → server/skills/<skill>/SKILL.md
skills/<skill>/references/<workflow>.md   → server/skills/<skill>/references/<workflow>.md

Разрешение пути источника:

1. Переменная окружения SKILLS_SRC (путь к корню репозитория навыков)
2. agent-skills.local.json — { "path": "../skills" }, относительно корня репозитория. Игнорируется Git; скопируйте agent-skills.local.json.example
3. skills-src/ — то, что CI и Docker-сборка используют как поставщика

Неявного поиска соседних каталогов нет. ../skills разрешается в то, что находится по этому пути, что заставляет локальную сборку молча расходиться с коммитом, из которого собирает CI.

CI, облачные развертывания и релизы читают agent-skills.lock.json и проверяют именно этот коммит навыков. Чтобы опубликовать изменения навыков вышестоящего проекта, обновите коммит в файле блокировки. Локальная разработка может указывать на любой checkout с помощью agent-skills.local.json или SKILLS_SRC.

Репозиторий навыков остается источником истины — этот пакет не поддерживает форк содержимого навыков. Новые навыки проходят автоматически, кроме тех, что указаны в небольшом блок-листе в bundle-skills.mjs. В настоящее время только gb-setup заблокирован, потому что он настраивает адаптер оболочки gb-call, а не сам GrowthBook.

Каталоги scripts/ для отдельных навыков не копируются. Относительные ссылки `references/foo.md` переписываются в квалифицированные `feature-flags/references/foo` paths so growthbook_read_skill может их разрешать.

Использование навыков с инструментами API

Встроенные навыки по-прежнему показывают рабочие процессы как:

gb-call GET /api/v1/projects
gb-call POST /api/v2/features ./payload.json

Этот MCP-сервер не вызывает gb-call из оболочки. Сопоставьте GET → growthbook_api_read и POST/PUT/PATCH/DELETE → growthbook_api_write с тем же путем и необязательной строкой JSON-тела. Инструкции сервера и вывод growthbook_read_skill включают это примечание о мосте.

Детали инструментов

growthbook_api_read / growthbook_api_write

{ "path": "/api/v1/projects" }
{ "method": "POST", "path": "/api/v2/features", "body": "{\"id\":\"my-flag\",...}" }

• Чтение: только GET (readOnlyHint: true)
• Запись: POST | PUT | PATCH | DELETE (destructiveHint: true)
• Возвращает необработанное тело ответа при 2xx
• При не-2xx возвращает действенную ошибку (isError: true), охватывающую сбои аутентификации, подсказки 404 для самостоятельного размещения и ограничения скорости
• Свободные пути нацелены на REST API GrowthBook
• Каждый запрос несет заголовки использования MCP (см. Телеметрия использования)

growthbook_list_skills / growthbook_read_skill

Регистрируются только когда GB_SKILLS_ENABLED не отключен.

• growthbook_list_skills возвращает точки входа в навыки верхнего уровня. Запись может содержать полный рабочий процесс или вести к дочерним рабочим процессам.
• growthbook_read_skill принимает указанное имя верхнего уровня или квалифицированный дочерний путь, названный загруженным навыком (feature-flags/references/flag-create), и возвращает полный Markdown (рабочий процесс + ограничения).

Телеметрия использования

Этот сервер никогда сам не отправляет телеметрию. Вместо этого каждый REST-вызов, сделанный growthbook_api_read / growthbook_api_write, включает заголовки, сообщающие экземпляру GrowthBook, что вызов пришел из MCP:

Заголовок	Пример	Содержимое
X-GB-MCP-Tool	growthbook_api_read	Инструмент, сделавший вызов
X-GB-MCP-Version	2.2.0	Версия этого сервера
X-GB-MCP-Transport	stdio	stdio или http
X-GB-MCP-Client	cursor/1.2.3	Имя/версия MCP-клиента из рукопожатия initialize, или его User-Agent в HTTP-режиме

GrowthBook записывает это через свою существующую продуктовую телеметрию, поэтому применяются те же элементы управления. На самостоятельно размещенном экземпляре установка DISABLE_TELEMETRY на бэкенде GrowthBook отключает это вместе с остальной телеметрией GrowthBook. Старые версии GrowthBook игнорируют заголовки. Инструменты навыков (growthbook_list_skills / growthbook_read_skill) обслуживаются локально и не делают запросов, поэтому не отслеживаются.

Разработка

git clone git@github.com:growthbook/skills.git ../skills
cp agent-skills.local.json.example agent-skills.local.json  # edit if not at ../skills

npm install
npm run build
npm start

Автономный HTTP-режим

По умолчанию сервер работает через stdio. Установите GB_MCP_TRANSPORT=http, чтобы запустить его как автономный HTTP-сервер, который предоставляет MCP по адресу /mcp (навыки + инструменты API) и /mcp/api (только возможности), за поверхностью защищенного ресурса OAuth 2.0 (метаданные RFC 9728 + WWW-Authenticate RFC 6750).

• GB_MCP_URL (обязательно в HTTP-режиме) — публичный базовый URL сервера. Он встраивается в ресурс OAuth (аудиторию) и метаданные защищенного ресурса, поэтому никогда не выводится из заголовков запросов. Сервер отказывается запускаться без него.
• GB_MCP_PORT (по умолчанию 3333) и GB_MCP_HOST (по умолчанию 127.0.0.1).
• Входящие bearer-токены проверяются через запрос к REST API GrowthBook; отклоненный токен получает HTTP 401 + WWW-Authenticate, чтобы клиент мог обновить токен.

Запускайте его в доверенной сети или привяжите к loopback. Для мультитенантного или публичного развертывания разместите перед ним собственный шлюз/аутентификацию.

Релизы

Выпуск релиза — осознанное действие: увеличьте версию в package.json, выполните npm run sync-version (обновляет manifest.json, server.json и .cursor-plugin/plugin.json), затем отправьте соответствующий тег v*:

git tag v2.0.0
git push origin v2.0.0

Этот тегированный коммит (с навыками, зафиксированными на момент выпуска) публикует:

• @growthbook/mcp в npm — предрелизы (версии с -, например 2.0.0-beta.1) идут под dist-тегом beta; стабильные версии становятся latest
• мультиархитектурный (amd64 + arm64) образ в ghcr.io/growthbook/growthbook-mcp (:<version>, плюс :<major>, :<major>.<minor> и :latest для стабильных релизов)
• запись в реестре MCP
• GitHub Release

Плагин Cursor не публикуется через CI: Cursor повторно проверяет плагин из ветки по умолчанию после того, как изменение версии попадает в нее.

Установите релиз с помощью npx @growthbook/mcp@<version> или получите ghcr.io/growthbook/growthbook-mcp:<version>.