GrowthBook

GrowthBook MCP Thin

Um servidor MCP leve para GrowthBook com quatro ferramentas:

Ferramenta	Propósito
growthbook_list_skills	Listar pontos de entrada de habilidades de nível superior (nome + descrição)
growthbook_read_skill	Retornar uma habilidade listada ou fluxo de trabalho filho qualificado (feature-flags ou feature-flags/references/flag-create)
growthbook_api_read	Passagem GET autenticada para a API do GrowthBook
growthbook_api_write	Passagem POST/PUT/PATCH/DELETE autenticada

A competência reside no repositório de habilidades e é empacotada no momento da compilação. A capacidade é dividida em ferramentas de API de leitura vs escrita (sem formatadores por endpoint) para que os clientes possam honrar readOnlyHint / destructiveHint corretamente.

As ferramentas são prefixadas com growthbook_ para permanecerem inequívocas quando um cliente tem múltiplos servidores MCP carregados.

Instalação / execução

npm install
npm run build

Aponte seu cliente MCP para o ponto 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"
      }
    }
  }
}

Ou execute o pacote publicado:

npx @growthbook/mcp

Variáveis de ambiente

Variável	Obrigatória	Padrão	Propósito
GB_API_KEY	Sim para stdio; opcional para OAuth HTTP	—	Chave de API do GrowthBook ou token de acesso pessoal
GB_API_URL	Não	https://api.growthbook.io	URL base da API (self-hosted) e emissor padrão do AS OAuth
GB_MCP_TRANSPORT	Não	stdio	stdio ou http
GB_MCP_PORT	Não	3333	Porta de escuta HTTP (quando transport=http)
GB_MCP_HOST	Não	127.0.0.1	Host de bind HTTP
GB_MCP_URL	Sim para HTTP	—	URL base pública do MCP gravada nos metadados do recurso OAuth (o servidor se recusa a iniciar em modo HTTP sem ela)
GB_MCP_KEEP_ALIVE_TIMEOUT_MS	Não	90000	Tempo limite de keep-alive ocioso no modo HTTP. Deve exceder o tempo limite ocioso de qualquer balanceador de carga à frente, ou o LB pode reutilizar uma conexão que o servidor já fechou e a solicitação falha com um 502
GB_OAUTH_ISSUER	Não	GB_API_URL	URL do emissor do AS OAuth do GrowthBook
GB_HTTP_HEADER_*	Não	—	Cabeçalhos de solicitação extras (ex.: GB_HTTP_HEADER_CF_ACCESS_TOKEN)
GB_SKILLS_ENABLED	Não	true	Defina como false / 0 para desabilitar as ferramentas 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

Os clientes se conectam a:

• http://127.0.0.1:3333/mcp — completo (habilidades + leitura/escrita de API)
• http://127.0.0.1:3333/mcp/api — somente capacidade (growthbook_api_read + growthbook_api_write)

Solicitações não autenticadas recebem 401 com WWW-Authenticate apontando para /.well-known/oauth-protected-resource, que anuncia o Servidor de Autorização do GrowthBook.

Antes de lidar com MCP, o servidor testa o REST do GrowthBook (GET /api/v1/) com o bearer. Um 401 desse teste (ou posteriormente de uma ferramenta de API) produz HTTP 401 com error="invalid_token" para que o cliente MCP possa atualizar — em vez de exibir "This API key has expired" como um erro de ferramenta. Um 403 é tratado como um bearer aceito (permissão negada ≠ token inválido) para que os clientes não sejam forçados a um loop de atualização.

Modo somente capacidade

HTTP (recomendado para remoto): aponte o cliente para /mcp/api em vez de /mcp:

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

Caminho	Ferramentas
/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 apenas

stdio / em todo o processo: defina env para que as habilidades nunca sejam registradas:

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

Quando as habilidades estão desabilitadas, apenas as ferramentas de leitura/escrita da API são registradas. growthbook_list_skills e growthbook_read_skill não são expostas.

Como as habilidades são empacotadas

npm run build   # tsc && bundle-skills

scripts/bundle-skills.mjs copia a árvore de habilidades de nível superior do checkout canônico de habilidades, preservando a estrutura:

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

Resolução do caminho de origem:

1. Variável de ambiente SKILLS_SRC (caminho para a raiz do repositório de habilidades)
2. agent-skills.local.json — { "path": "../skills" }, relativo à raiz do repositório. Ignorado pelo git; copie agent-skills.local.json.example
3. skills-src/ — o que CI e o build Docker fornecem

Não há busca implícita de irmãos. ../skills resolve para o que quer que esteja nesse caminho, o que faz um build local discordar silenciosamente do commit que o CI compila.

CI, implantações em nuvem e lançamentos todos leem agent-skills.lock.json e fazem checkout desse commit exato de habilidades. Para enviar mudanças de habilidades upstream, atualize o commit no arquivo de bloqueio. O desenvolvimento local pode apontar para qualquer checkout com agent-skills.local.json ou SKILLS_SRC.

O repositório de habilidades permanece a fonte da verdade — este pacote não mantém um fork do conteúdo de habilidades. Novas habilidades fluem automaticamente, exceto aquelas nomeadas na pequena lista de bloqueio em bundle-skills.mjs. Atualmente apenas gb-setup é bloqueada porque configura o adaptador de shell gb-call em vez do próprio GrowthBook.

Diretórios scripts/ por habilidade não são copiados. Links relativos `references/foo.md` são reescritos para `feature-flags/references/foo` paths so growthbook_read_skill qualificados para que possam resolvê-los.

Usando habilidades com as ferramentas de API

Habilidades empacotadas ainda mostram fluxos de trabalho como:

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

Este servidor MCP não faz shell out para gb-call. Mapeie GET → growthbook_api_read e POST/PUT/PATCH/DELETE → growthbook_api_write com o mesmo caminho e string de corpo JSON opcional. As instruções do servidor e a saída de growthbook_read_skill incluem esta nota de ponte.

Detalhes das ferramentas

growthbook_api_read / growthbook_api_write

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

• Leitura: GET apenas (readOnlyHint: true)
• Escrita: POST | PUT | PATCH | DELETE (destructiveHint: true)
• Retorna o corpo bruto da resposta em 2xx
• Em não-2xx, retorna um erro acionável (isError: true) cobrindo falhas de autenticação, dicas de 404 self-hosted e limites de taxa
• Caminhos de forma livre visam a API REST do GrowthBook

growthbook_list_skills / growthbook_read_skill

Apenas registradas quando GB_SKILLS_ENABLED não está desabilitado.

• growthbook_list_skills retorna pontos de entrada de habilidades de nível superior. Uma entrada pode conter um fluxo de trabalho completo ou rotear para fluxos de trabalho filhos.
• growthbook_read_skill aceita um nome de nível superior listado ou um caminho filho qualificado nomeado por uma habilidade carregada (feature-flags/references/flag-create) e retorna o markdown completo (fluxo de trabalho + salvaguardas).

Desenvolvimento

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 autônomo

Por padrão, o servidor roda sobre stdio. Defina GB_MCP_TRANSPORT=http para executá-lo como um servidor HTTP autônomo que expõe MCP em /mcp (habilidades + ferramentas de API) e /mcp/api (somente capacidade), atrás de uma superfície de recurso protegido OAuth 2.0 (metadados RFC 9728 + WWW-Authenticate RFC 6750).

• GB_MCP_URL (obrigatória no modo HTTP) — a URL base pública do servidor. Ela é gravada no recurso OAuth (audiência) e nos metadados do recurso protegido, então nunca é derivada de cabeçalhos de solicitação. O servidor se recusa a iniciar sem ela.
• GB_MCP_PORT (padrão 3333) e GB_MCP_HOST (padrão 127.0.0.1).
• Bearers recebidos são validados testando a API REST do GrowthBook; um token rejeitado recebe HTTP 401 + WWW-Authenticate para que o cliente possa atualizar.

Execute-o em uma rede confiável ou vinculado ao loopback. Para uma implantação multi-tenant ou pública, coloque seu próprio gateway/auth à frente.

Lançamentos

Cortar um lançamento é deliberado: aumente a versão em package.json, depois envie uma tag v* correspondente:

git tag v2.0.0
git push origin v2.0.0

Esse commit marcado (com habilidades congeladas no momento do corte) publica:

• @growthbook/mcp para npm — pré-lançamentos (versões com um -, ex.: 2.0.0-beta.1) vão sob a dist-tag beta; versões estáveis tornam-se latest
• uma imagem multi-arquitetura (amd64 + arm64) para ghcr.io/growthbook/growthbook-mcp (:<version>, mais :<major>, :<major>.<minor> e :latest para lançamentos estáveis)
• uma entrada no registro MCP
• um GitHub Release

Instale um lançamento com npx @growthbook/mcp@<version> ou puxe ghcr.io/growthbook/growthbook-mcp:<version>.