GrowthBook

GrowthBook MCP Thin

Um servidor MCP leve para GrowthBook com quatro ferramentas:

Ferramenta	Finalidade
growthbook_list_skills	Listar as skills do agente GrowthBook incluídas (nome + descrição)
growthbook_read_skill	Retornar o markdown completo da skill (fluxo de trabalho + diretrizes)
growthbook_api_read	Passagem GET autenticada para a API do GrowthBook
growthbook_api_write	Passagem POST/PUT/PATCH/DELETE autenticada

A competência vive no repositório skills 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 vários servidores MCP carregados.

Instalação / execução

npm install
npm run build

Aponte seu cliente MCP para o entrypoint 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	Finalidade
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, inserida nos metadados do recurso OAuth (o servidor se recusa a iniciar em modo HTTP sem ela)
GB_OAUTH_ISSUER	Não	GB_API_URL	URL do emissor do AS OAuth do GrowthBook
GB_HTTP_HEADER_*	Não	—	Cabeçalhos de requisição extras (ex.: GB_HTTP_HEADER_CF_ACCESS_TOKEN)
GB_SKILLS_ENABLED	Não	true	Defina como false / 0 para desabilitar as ferramentas de skill

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 (skills + leitura/escrita da API)
• http://127.0.0.1:3333/mcp/api — somente capacidade (growthbook_api_read + growthbook_api_write)

Requisições não autenticadas recebem 401 com WWW-Authenticate apontando para /.well-known/oauth-protected-resource, que anuncia o Authorization Server do GrowthBook.

Antes de processar o MCP, o servidor verifica o REST do GrowthBook (GET /api/v1/) com o bearer. Um 401 dessa verificação (ou posteriormente de uma ferramenta de API) gera HTTP 401 com error="invalid_token" para que o cliente MCP possa renovar — em vez de apresentar "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 renovaçã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 (exceto se GB_SKILLS_ENABLED=false)
/mcp/api	growthbook_api_read, growthbook_api_write apenas

stdio / no processo: defina a env para que as skills nunca sejam registradas:

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

Quando as skills 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 skills são empacotadas

npm run build   # tsc && bundle-skills

scripts/bundle-skills.mjs copia cada skills/*/SKILL.md do checkout canônico de skills para server/skills/<name>.md.

Resolução do caminho de origem:

1. Variável de ambiente SKILLS_SRC (caminho para a raiz do repositório de skills), ou
2. ../skills (diretório irmão)

O repositório de skills permanece a fonte da verdade — este pacote nunca faz fork do conteúdo das skills.

Usando skills com as ferramentas de API

As skills incluídas 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 chamadas de shell 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 essa 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: somente GET (readOnlyHint: true)
• Escrita: POST | PUT | PATCH | DELETE (destructiveHint: true)
• Retorna o corpo da resposta bruta em 2xx
• Em não-2xx, retorna um erro acionável (isError: true) cobrindo falhas de autenticação, dicas de 404 para self-hosted e limites de taxa
• Caminhos livres têm como alvo a API REST do GrowthBook

growthbook_list_skills / growthbook_read_skill

Somente registradas quando GB_SKILLS_ENABLED não está desabilitado. growthbook_read_skill retorna o conteúdo completo de SKILL.md para que o agente possa seguir as etapas do fluxo de trabalho e as diretrizes.

Desenvolvimento

# Requires a sibling checkout at ../skills (or SKILLS_SRC)
npm install
npm run build
npm start

Modo HTTP autônomo

Por padrão, o servidor roda via stdio. Defina GB_MCP_TRANSPORT=http para executá-lo como um servidor HTTP autônomo que expõe o MCP em /mcp (skills + 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ório no modo HTTP) — a URL base pública do servidor. Ela é inserida no recurso OAuth (audiência) e nos metadados do recurso protegido, portanto nunca é derivada dos cabeçalhos da requisiçã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).
• Os bearers recebidos são validados verificando a API REST do GrowthBook; um token rejeitado recebe HTTP 401 + WWW-Authenticate para que o cliente possa renovar.

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

Lançamentos

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

git tag v2.0.0
git push origin v2.0.0

Esse commit com tag (com as skills 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>, além de :<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>.