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 respetar readOnlyHint / destructiveHint correctamente.

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

Plugin de Cursor

Instala GrowthBook desde el Marketplace de Cursor. El plugin conecta Cursor al servidor alojado en https://mcp.growthbook.io/mcp; la primera llamada a una herramienta abre un inicio de sesión de GrowthBook para autorizarlo. Los usuarios de GrowthBook autoalojado deben configurar el servidor manualmente como se describe a continuación.

El plugin está definido por .cursor-plugin/plugin.json y mcp.json. Para probar cambios localmente, copia el repositorio en ~/.cursor/plugins/local/growthbook y ejecuta Developer: Reload Window.

Instalación / ejecución

npm install
npm run build

Apunta tu 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 ejecuta el paquete publicado:

npx @growthbook/mcp

Variables de entorno

Variable	Requerida	Predeterminada	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 de 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 incluida en los metadatos de recursos 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 cerró y la solicitud falla con un 502
OPENAI_APPS_CHALLENGE_TOKEN	No	—	Se sirve como texto plano en /.well-known/openai-apps-challenge para la verificación de dominio del plugin de OpenAI (modo HTTP); la ruta devuelve 404 cuando no está configurada
GB_OAUTH_ISSUER	No	GB_API_URL	URL del emisor AS de OAuth de GrowthBook
GB_HTTP_HEADER_*	No	—	Encabezados de solicitud adicionales (p. ej., GB_HTTP_HEADER_CF_ACCESS_TOKEN)
GB_SKILLS_ENABLED	No	true	Configúralo en 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): apunta 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: configura el entorno 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; copia 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 agent-skills.lock.json y verifican ese commit exacto de habilidades. Para enviar cambios de habilidades ascendentes, actualiza 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 puede resolverlos.

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. Mapea 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
• Cada solicitud lleva encabezados de uso de MCP (ver Telemetría de uso)

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).

Telemetría de uso

Este servidor nunca envía telemetría a ningún lugar por sí mismo. En cambio, cada llamada REST realizada por growthbook_api_read / growthbook_api_write incluye encabezados que le indican a la instancia de GrowthBook con la que está hablando que la llamada provino del MCP:

Encabezado	Ejemplo	Contenido
X-GB-MCP-Tool	growthbook_api_read	La herramienta que hizo la llamada
X-GB-MCP-Version	2.2.0	La versión de este servidor
X-GB-MCP-Transport	stdio	stdio o http
X-GB-MCP-Client	cursor/1.2.3	El nombre/versión del cliente MCP del apretón de manos de inicialización, o su User-Agent en modo HTTP

GrowthBook registra estos a través de su telemetría de producto existente, por lo que se aplican los mismos controles. En una instancia autoalojada, configurar DISABLE_TELEMETRY en el back-end de GrowthBook desactiva esto junto con el resto de la telemetría de GrowthBook. Las versiones más antiguas de GrowthBook ignoran los encabezados. Las herramientas de habilidades (growthbook_list_skills / growthbook_read_skill) se sirven localmente y no hacen solicitudes, por lo que no se rastrean.

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. Configura 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 + RFC 6750 WWW-Authenticate).

• GB_MCP_URL (requerido en modo HTTP) — la URL base pública del servidor. Se incluye en el recurso OAuth (audiencia) y en los metadatos del recurso protegido, por lo que nunca se deriva de los encabezados 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útalo en una red confiable o vinculado a loopback. Para un despliegue multiinquilino o público, colócalo detrás de tu propia puerta de enlace/autenticación.

Lanzamientos

Recortar un lanzamiento es deliberado: incrementa la versión en package.json, ejecuta npm run sync-version (actualiza manifest.json, server.json y .cursor-plugin/plugin.json), luego empuja 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 recorte) 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 de MCP
• un lanzamiento de GitHub

El plugin de Cursor no se publica por CI: Cursor vuelve a revisar el plugin desde la rama predeterminada después de que el incremento de versión aterrice.

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