GrowthBook

GrowthBook MCP Thin

Un serveur MCP léger pour GrowthBook avec quatre outils :

Outil	Objectif
growthbook_list_skills	Lister les points d'entrée de compétences de premier niveau (nom + description)
growthbook_read_skill	Retourner une compétence listée ou un workflow enfant qualifié (feature-flags ou feature-flags/references/flag-create)
growthbook_api_read	Passerelle GET authentifiée vers l'API GrowthBook
growthbook_api_write	Passerelle POST/PUT/PATCH/DELETE authentifiée

Les compétences résident dans le dépôt skills et sont regroupées au moment de la compilation. Les capacités sont divisées en outils API de lecture vs écriture (sans formatteurs par point de terminaison) afin que les clients puissent honorer correctement readOnlyHint / destructiveHint.

Les outils sont préfixés avec growthbook_ pour rester sans ambiguïté lorsqu'un client a plusieurs serveurs MCP chargés.

Installation / exécution

npm install
npm run build

Pointez votre client MCP vers le point d'entrée compilé :

{
  "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"
      }
    }
  }
}

Ou exécutez le package publié :

npx @growthbook/mcp

Variables d'environnement

Variable	Requise	Défaut	Objectif
GB_API_KEY	Oui pour stdio ; optionnelle pour HTTP OAuth	—	Clé API GrowthBook ou jeton d'accès personnel
GB_API_URL	Non	https://api.growthbook.io	URL de base de l'API (auto-hébergé) et émetteur AS OAuth par défaut
GB_MCP_TRANSPORT	Non	stdio	stdio ou http
GB_MCP_PORT	Non	3333	Port d'écoute HTTP (lorsque transport=http)
GB_MCP_HOST	Non	127.0.0.1	Hôte de liaison HTTP
GB_MCP_URL	Oui pour HTTP	—	URL de base MCP publique estampillée dans les métadonnées de ressource OAuth (le serveur refuse de démarrer en mode HTTP sans elle)
GB_MCP_KEEP_ALIVE_TIMEOUT_MS	Non	90000	Délai d'expiration de maintien en vie en mode HTTP. Doit dépasser le délai d'expiration inactif de tout équilibreur de charge en amont, sinon l'équilibreur peut réutiliser une connexion déjà fermée par le serveur et la requête échoue avec une erreur 502
GB_OAUTH_ISSUER	Non	GB_API_URL	URL de l'émetteur AS OAuth GrowthBook
GB_HTTP_HEADER_*	Non	—	En-têtes de requête supplémentaires (par ex. GB_HTTP_HEADER_CF_ACCESS_TOKEN)
GB_SKILLS_ENABLED	Non	true	Définir sur false / 0 pour désactiver les outils de compétences

Mode 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

Les clients se connectent à :

• http://127.0.0.1:3333/mcp — complet (compétences + lecture/écriture API)
• http://127.0.0.1:3333/mcp/api — capacités uniquement (growthbook_api_read + growthbook_api_write)

Les requêtes non authentifiées reçoivent 401 avec WWW-Authenticate pointant vers /.well-known/oauth-protected-resource, qui annonce le serveur d'autorisation GrowthBook.

Avant de traiter MCP, le serveur sonde le REST GrowthBook (GET /api/v1/) avec le porteur. Un 401 de cette sonde (ou plus tard d'un outil API) produit HTTP 401 avec error="invalid_token" afin que le client MCP puisse actualiser — au lieu de faire apparaître "This API key has expired" comme une erreur d'outil. Un 403 est traité comme un porteur accepté (permission refusée ≠ jeton invalide) afin que les clients ne soient pas forcés dans une boucle d'actualisation.

Mode capacités uniquement

HTTP (recommandé pour le distant) : pointez le client vers /mcp/api au lieu de /mcp :

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

Chemin	Outils
/mcp	growthbook_list_skills, growthbook_read_skill, growthbook_api_read, growthbook_api_write (sauf si GB_SKILLS_ENABLED=false)
/mcp/api	growthbook_api_read, growthbook_api_write uniquement

stdio / à l'échelle du processus : définissez l'environnement pour que les compétences ne soient jamais enregistrées :

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

Lorsque les compétences sont désactivées, seuls les outils de lecture/écriture API sont enregistrés. growthbook_list_skills et growthbook_read_skill ne sont pas exposés.

Comment les compétences sont regroupées

npm run build   # tsc && bundle-skills

scripts/bundle-skills.mjs copie l'arborescence de compétences de premier niveau depuis le checkout canonique des compétences, en préservant la structure :

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

Résolution du chemin source :

1. SKILLS_SRC variable d'environnement (chemin vers la racine du dépôt de compétences)
2. agent-skills.local.json — { "path": "../skills" }, relatif à la racine du dépôt. Gitignoré ; copiez agent-skills.local.json.example
3. skills-src/ — ce que CI et la construction Docker fournissent

Il n'y a pas de recherche implicite de frères. ../skills se résout à ce qui se trouve à ce chemin, ce qui fait qu'une construction locale peut silencieusement diverger du commit que CI construit.

CI, les déploiements cloud et les versions lisent tous agent-skills.lock.json et extraient ce commit exact de compétences. Pour publier des modifications de compétences en amont, mettez à jour le commit dans le fichier de verrouillage. Le développement local peut pointer vers n'importe quel checkout avec agent-skills.local.json ou SKILLS_SRC.

Le dépôt de compétences reste la source de vérité — ce package ne maintient pas de fork du contenu des compétences. Les nouvelles compétences circulent automatiquement, sauf celles nommées dans la petite liste de blocage dans bundle-skills.mjs. Actuellement, seul gb-setup est bloqué car il configure l'adaptateur shell gb-call plutôt que GrowthBook lui-même.

Les répertoires scripts/ par compétence ne sont pas copiés. Les liens relatifs `references/foo.md` sont réécrits en `feature-flags/references/foo` paths so growthbook_read_skill qualifiés pour pouvoir les résoudre.

Utilisation des compétences avec les outils API

Les compétences regroupées affichent toujours les workflows comme :

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

Ce serveur MCP ne fait pas appel à gb-call. Mappez GET → growthbook_api_read et POST/PUT/PATCH/DELETE → growthbook_api_write avec le même chemin et une chaîne de corps JSON optionnelle. Les instructions du serveur et la sortie growthbook_read_skill incluent cette note de pontage.

Détail des outils

growthbook_api_read / growthbook_api_write

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

• Lecture : GET uniquement (readOnlyHint: true)
• Écriture : POST | PUT | PATCH | DELETE (destructiveHint: true)
• Retourne le corps de réponse brut sur 2xx
• Sur non-2xx, retourne une erreur exploitable (isError: true) couvrant les échecs d'authentification, les indices 404 auto-hébergés et les limites de débit
• Les chemins libres ciblent l'API REST GrowthBook
• Chaque requête porte des en-têtes d'utilisation MCP (voir Télémétrie d'utilisation)

growthbook_list_skills / growthbook_read_skill

Enregistrés uniquement lorsque GB_SKILLS_ENABLED n'est pas désactivé.

• growthbook_list_skills retourne les points d'entrée de compétences de premier niveau. Une entrée peut contenir un workflow complet ou router vers des workflows enfants.
• growthbook_read_skill accepte un nom de premier niveau listé ou un chemin enfant qualifié nommé par une compétence chargée (feature-flags/references/flag-create) et retourne le markdown complet (workflow + garde-fous).

Télémétrie d'utilisation

Ce serveur n'envoie jamais de télémétrie lui-même. Au lieu de cela, chaque appel REST effectué par growthbook_api_read / growthbook_api_write inclut des en-têtes qui indiquent à l'instance GrowthBook qu'elle parle que l'appel provient du MCP :

En-tête	Exemple	Contenu
X-GB-MCP-Tool	growthbook_api_read	L'outil qui a effectué l'appel
X-GB-MCP-Version	2.1.0	La version de ce serveur
X-GB-MCP-Transport	stdio	stdio ou http
X-GB-MCP-Client	cursor/1.2.3	Le nom/version du client MCP depuis la poignée de main d'initialisation, ou son User-Agent en mode HTTP

GrowthBook les enregistre via sa télémétrie produit existante, donc les mêmes contrôles s'appliquent. Sur une instance auto-hébergée, définir DISABLE_TELEMETRY sur le back-end GrowthBook désactive cela ainsi que le reste de la télémétrie de GrowthBook. Les versions plus anciennes de GrowthBook ignorent les en-têtes. Les outils de compétences (growthbook_list_skills / growthbook_read_skill) sont servis localement et ne font aucune requête, donc ils ne sont pas suivis.

Développement

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

Mode HTTP autonome

Par défaut, le serveur fonctionne sur stdio. Définissez GB_MCP_TRANSPORT=http pour l'exécuter comme serveur HTTP autonome qui expose MCP à /mcp (compétences + outils API) et /mcp/api (capacités uniquement), derrière une surface de ressource protégée OAuth 2.0 (métadonnées RFC 9728 + WWW-Authenticate RFC 6750).

• GB_MCP_URL (requis en mode HTTP) — l'URL de base publique du serveur. Elle est estampillée dans la ressource OAuth (audience) et les métadonnées de ressource protégée, donc elle n'est jamais dérivée des en-têtes de requête. Le serveur refuse de démarrer sans elle.
• GB_MCP_PORT (défaut 3333) et GB_MCP_HOST (défaut 127.0.0.1).
• Les porteurs entrants sont validés en sondant l'API REST GrowthBook ; un jeton rejeté obtient HTTP 401 + WWW-Authenticate afin que le client puisse actualiser.

Exécutez-le sur un réseau de confiance ou lié à loopback. Pour un déploiement multi-tenant ou public, placez votre propre passerelle/authentification devant.

Versions

Publier une version est délibéré : augmentez la version dans package.json, puis poussez une balise v* correspondante :

git tag v2.0.0
git push origin v2.0.0

Ce commit tagué (avec les compétences figées au moment de la coupe) publie :

• @growthbook/mcp sur npm — les préversions (versions avec un -, par ex. 2.0.0-beta.1) vont sous la balise de distribution beta ; les versions stables deviennent latest
• une image multi-arch (amd64 + arm64) vers ghcr.io/growthbook/growthbook-mcp (:<version>, plus :<major>, :<major>.<minor> et :latest pour les versions stables)
• une entrée dans le registre MCP
• une version GitHub

Installez une version avec npx @growthbook/mcp@<version> ou tirez ghcr.io/growthbook/growthbook-mcp:<version>.