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 autenticada POST/PUT/PATCH/DELETE

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

Plugin do Cursor

Instale o GrowthBook no Cursor Marketplace. O plugin conecta o Cursor ao servidor hospedado em https://mcp.growthbook.io/mcp; a primeira chamada de ferramenta abre um login do GrowthBook para autorizá-lo. Usuários de GrowthBook auto-hospedado devem configurar o servidor manualmente conforme descrito abaixo.

O plugin é definido por .cursor-plugin/plugin.json e mcp.json. Para testar alterações localmente, copie o repositório para ~/.cursor/plugins/local/growthbook e execute Developer: Reload Window.

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 (auto-hospedado) e emissor AS OAuth padrão
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 vinculação HTTP
GB_MCP_URL	Sim para HTTP	—	URL base MCP pública carimbada nos metadados de 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 em 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 502
OPENAI_APPS_CHALLENGE_TOKEN	Não	—	Servido como texto simples em /.well-known/openai-apps-challenge para verificação de domínio do plugin OpenAI (modo HTTP); a rota retorna 404 quando não definido
GB_OAUTH_ISSUER	Não	GB_API_URL	URL do emissor 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 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 verifica o REST do GrowthBook (GET /api/v1/) com o bearer. Um 401 dessa verificação (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 estiver naquele 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 verificam exatamente esse commit de habilidades. Para enviar alterações 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 está 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 pode 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 executa 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 de resposta bruto em 2xx
• Em não-2xx, retorna um erro acionável (isError: true) cobrindo falhas de autenticação, dicas de 404 auto-hospedado e limites de taxa
• Caminhos livres visam a API REST do GrowthBook
• Cada solicitação carrega cabeçalhos de uso MCP (veja Telemetria de uso)

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

Telemetria de uso

Este servidor nunca envia telemetria para lugar nenhum por conta própria. Em vez disso, cada chamada REST feita por growthbook_api_read / growthbook_api_write inclui cabeçalhos que informam à instância do GrowthBook com a qual está falando que a chamada veio do MCP:

Cabeçalho	Exemplo	Conteúdo
X-GB-MCP-Tool	growthbook_api_read	A ferramenta que fez a chamada
X-GB-MCP-Version	2.2.0	A versão deste servidor
X-GB-MCP-Transport	stdio	stdio ou http
X-GB-MCP-Client	cursor/1.2.3	O nome/versão do cliente MCP do handshake de inicialização, ou seu User-Agent em modo HTTP

O GrowthBook registra isso através de sua telemetria de produto existente, então os mesmos controles se aplicam. Em uma instância auto-hospedada, definir DISABLE_TELEMETRY no back-end do GrowthBook desativa isso junto com o restante da telemetria do GrowthBook. Versões mais antigas do GrowthBook ignoram os cabeçalhos. Ferramentas de habilidades (growthbook_list_skills / growthbook_read_skill) são servidas localmente e não fazem solicitações, então não são rastreadas.

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

• GB_MCP_URL (obrigatório em modo HTTP) — a URL base pública do servidor. É carimbada 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 verificando 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 a 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, execute npm run sync-version (atualiza manifest.json, server.json e .cursor-plugin/plugin.json), então 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 se tornam 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

O plugin do Cursor não é publicado pelo CI: o Cursor re-revisa o plugin do branch padrão após o aumento de versão ser aplicado.

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