GrowthBook

GrowthBook MCP Thin

Un servidor MCP ligero para GrowthBook con cuatro herramientas:

Herramienta	Propósito
growthbook_list_skills	Listar los puntos de entrada de habilidades de nivel superior (nombre + descripción)
growthbook_read_skill	Devolver una habilidad listada o un flujo de trabajo hijo calificado (feature-flags o feature-flags/references/flag-create)
growthbook_api_read	Paso directo GET autenticado a la API de GrowthBook
growthbook_api_write	Paso directo POST/PUT/PATCH/DELETE autenticado

La competencia vive en el repositorio de habilidades y está empaquetada en tiempo de compilación. La capacidad se divide en herramientas de API de lectura vs escritura (sin formateadores por endpoint) para que los clientes puedan honrar readOnlyHint / destructiveHint correctamente.

Las herramientas tienen el prefijo growthbook_ para que no sean ambiguas cuando un cliente tiene múltiples servidores MCP cargados.

Instalación / ejecución

npm install
npm run build

Apunte su cliente MCP al punto de entrada compilado:

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

O ejecute el paquete publicado:

npx @growthbook/mcp

Variables de entorno

Variable	Requerida	Predeterminado	Propósito
GB_API_KEY	Sí para stdio; opcional para OAuth HTTP	—	Clave de API de GrowthBook o token de acceso personal
GB_API_URL	No	https://api.growthbook.io	URL base de la API (autoalojado) y emisor AS OAuth predeterminado
GB_MCP_TRANSPORT	No	stdio	stdio o http
GB_MCP_PORT	No	3333	Puerto de escucha HTTP (cuando transport=http)
GB_MCP_HOST	No	127.0.0.1	Host de enlace HTTP
GB_MCP_URL	Sí para HTTP	—	URL base pública de MCP estampada en los metadatos del recurso OAuth (el servidor se niega a iniciar en modo HTTP sin ella)
GB_MCP_KEEP_ALIVE_TIMEOUT_MS	No	90000	Tiempo de espera de keep-alive inactivo en modo HTTP. Debe superar el tiempo de espera inactivo de cualquier balanceador de carga al frente, o el LB puede reutilizar una conexión que el servidor ya ha cerrado y la solicitud falla con un 502
GB_OAUTH_ISSUER	No	GB_API_URL	URL del emisor AS OAuth de GrowthBook
GB_HTTP_HEADER_*	No	—	Cabeceras de solicitud adicionales (p. ej., GB_HTTP_HEADER_CF_ACCESS_TOKEN)
GB_SKILLS_ENABLED	No	true	Establecer a false / 0 para deshabilitar las herramientas de habilidades

Modo 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

Los clientes se conectan a:

• http://127.0.0.1:3333/mcp — completo (habilidades + lectura/escritura de API)
• http://127.0.0.1:3333/mcp/api — solo capacidad (growthbook_api_read + growthbook_api_write)

Las solicitudes no autenticadas reciben 401 con WWW-Authenticate apuntando a /.well-known/oauth-protected-resource, que anuncia el Servidor de Autorización de GrowthBook.

Antes de manejar MCP, el servidor sondea REST de GrowthBook (GET /api/v1/) con el bearer. Un 401 de esa sonda (o posteriormente de una herramienta de API) produce HTTP 401 con error="invalid_token" para que el cliente MCP pueda actualizar — en lugar de mostrar "This API key has expired" como un error de herramienta. Un 403 se trata como un bearer aceptado (permiso denegado ≠ token inválido) para que los clientes no se vean forzados a un bucle de actualización.

Modo solo capacidad

HTTP (recomendado para remoto): apunte el cliente a /mcp/api en lugar de /mcp:

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

Ruta	Herramientas
/mcp	growthbook_list_skills, growthbook_read_skill, growthbook_api_read, growthbook_api_write (a menos que GB_SKILLS_ENABLED=false)
/mcp/api	growthbook_api_read, growthbook_api_write solamente

stdio / a nivel de proceso: establezca env para que las habilidades nunca se registren:

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

Cuando las habilidades están deshabilitadas, solo se registran las herramientas de lectura/escritura de API. growthbook_list_skills y growthbook_read_skill no se exponen.

Cómo se empaquetan las habilidades

npm run build   # tsc && bundle-skills

scripts/bundle-skills.mjs copia el árbol de habilidades de nivel superior desde el checkout canónico de habilidades, preservando la estructura:

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

Resolución de la ruta de origen:

1. Variable de entorno SKILLS_SRC (ruta a la raíz del repositorio de habilidades)
2. agent-skills.local.json — { "path": "../skills" }, relativo a la raíz del repositorio. Ignorado por git; copie agent-skills.local.json.example
3. skills-src/ — lo que CI y la compilación de Docker proveen

No hay búsqueda implícita de hermanos. ../skills se resuelve a lo que sea que esté en esa ruta, lo que hace que una compilación local discrepe silenciosamente del commit desde el que CI compila.

CI, despliegues en la nube y lanzamientos leen todos agent-skills.lock.json y verifican ese commit exacto de habilidades. Para enviar cambios de habilidades ascendentes, actualice el commit en el archivo de bloqueo. El desarrollo local puede apuntar a cualquier checkout con agent-skills.local.json o SKILLS_SRC.

El repositorio de habilidades sigue siendo la fuente de verdad — este paquete no mantiene un fork del contenido de habilidades. Las nuevas habilidades fluyen automáticamente, excepto aquellas nombradas en la pequeña lista de bloqueo en bundle-skills.mjs. Actualmente solo gb-setup está bloqueada porque configura el adaptador de shell gb-call en lugar de GrowthBook en sí.

Los directorios scripts/ por habilidad no se copian. Los enlaces relativos `references/foo.md` se reescriben a `feature-flags/references/foo` paths so growthbook_read_skill calificados para que puedan resolverse.

Uso de habilidades con las herramientas de API

Las habilidades empaquetadas aún muestran flujos de trabajo como:

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

Este servidor MCP no ejecuta gb-call. Mapee GET → growthbook_api_read y POST/PUT/PATCH/DELETE → growthbook_api_write con la misma ruta y cadena de cuerpo JSON opcional. Las instrucciones del servidor y la salida de growthbook_read_skill incluyen esta nota de puente.

Detalle de herramientas

growthbook_api_read / growthbook_api_write

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

• Lectura: solo GET (readOnlyHint: true)
• Escritura: POST | PUT | PATCH | DELETE (destructiveHint: true)
• Devuelve el cuerpo de respuesta sin procesar en 2xx
• En no-2xx, devuelve un error procesable (isError: true) que cubre fallos de autenticación, sugerencias de 404 autoalojado y límites de tasa
• Las rutas de forma libre apuntan a la API REST de GrowthBook

growthbook_list_skills / growthbook_read_skill

Solo se registran cuando GB_SKILLS_ENABLED no está deshabilitado.

• growthbook_list_skills devuelve los puntos de entrada de habilidades de nivel superior. Una entrada puede contener un flujo de trabajo completo o enrutar a flujos de trabajo hijos.
• growthbook_read_skill acepta un nombre de nivel superior listado o una ruta hija calificada nombrada por una habilidad cargada (feature-flags/references/flag-create) y devuelve el markdown completo (flujo de trabajo + salvaguardas).

Desarrollo

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

Modo HTTP independiente

Por defecto, el servidor se ejecuta sobre stdio. Establezca GB_MCP_TRANSPORT=http para ejecutarlo como un servidor HTTP independiente que expone MCP en /mcp (habilidades + herramientas de API) y /mcp/api (solo capacidad), detrás de una superficie de recurso protegido OAuth 2.0 (metadatos RFC 9728 + WWW-Authenticate RFC 6750).

• GB_MCP_URL (requerido en modo HTTP) — la URL base pública del servidor. Se estampa en el recurso OAuth (audiencia) y en los metadatos del recurso protegido, por lo que nunca se deriva de las cabeceras de solicitud. El servidor se niega a iniciar sin ella.
• GB_MCP_PORT (predeterminado 3333) y GB_MCP_HOST (predeterminado 127.0.0.1).
• Los bearers entrantes se validan sondeando la API REST de GrowthBook; un token rechazado obtiene HTTP 401 + WWW-Authenticate para que el cliente pueda actualizar.

Ejecútelo en una red confiable o vinculado a loopback. Para un despliegue multiinquilino o público, colóquelo detrás de su propia puerta de enlace/autenticación.

Lanzamientos

Cortar un lanzamiento es deliberado: aumente la versión en package.json, luego empuje una etiqueta v* coincidente:

git tag v2.0.0
git push origin v2.0.0

Ese commit etiquetado (con habilidades congeladas en el momento del corte) publica:

• @growthbook/mcp a npm — los prelanzamientos (versiones con un -, p. ej., 2.0.0-beta.1) van bajo la etiqueta de distribución beta; las versiones estables se convierten en latest
• una imagen multiarquitectura (amd64 + arm64) a ghcr.io/growthbook/growthbook-mcp (:<version>, más :<major>, :<major>.<minor> y :latest para lanzamientos estables)
• una entrada en el registro MCP
• un Lanzamiento de GitHub

Instale un lanzamiento con npx @growthbook/mcp@<version> o extraiga ghcr.io/growthbook/growthbook-mcp:<version>.