@growthbook/mcp 1.5.1 → 1.6.0

package/README.md

@@ -17,6 +17,24 @@ Use the following env variables to configure the MCP server.
 | GB_EMAIL      | Required | Your email address used with GrowthBook. Used when creating feature flags and experiments.|
 | GB_API_URL    | Optional | Your GrowthBook API URL. Defaults to `https://api.growthbook.io`. |
 | GB_APP_ORIGIN | Optional | Your GrowthBook app URL Defaults to `https://app.growthbook.io`.  |
+| GB_HTTP_HEADER_* | Optional | Custom HTTP headers to include in all GrowthBook API requests. Use the pattern `GB_HTTP_HEADER_<NAME>` where `<NAME>` is converted to proper HTTP header format (underscores become hyphens). Examples: `GB_HTTP_HEADER_X_TENANT_ID=abc123` becomes `X-Tenant-ID: abc123`, `GB_HTTP_HEADER_CF_ACCESS_TOKEN=<token>` becomes `Cf-Access-Token: <token>`. Multiple custom headers can be configured. |
 
+**Custom Headers Examples**
+
+For multi-tenant deployments or proxy configurations, you can add custom headers:
+
+```bash
+# Multi-tenant identification
+GB_HTTP_HEADER_X_TENANT_ID=tenant-123
+
+# Cloudflare Access proxy authentication
+GB_HTTP_HEADER_CF_ACCESS_TOKEN=eyJhbGciOiJSUzI1NiIs...
+```
+
+**Security Best Practices**
+- Always use HTTPS for API communication (default for GrowthBook Cloud)
+- Store API keys and sensitive headers in environment variables, never hardcode them
+- Use the Authorization header (via GB_API_KEY) for authentication
+- Custom headers are useful for multi-tenant scenarios, proxy routing, or additional context
 
 Add the MCP server to your AI tool of choice. See the [official docs](https://docs.growthbook.io/integrations/mcp) for complete a complete guide.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@growthbook/mcp",
   "mcpName": "io.github.growthbook/growthbook-mcp",
-  "version": "1.5.1",
+  "version": "1.6.0",
   "description": "MCP Server for interacting with GrowthBook",
   "access": "public",
   "homepage": "https://github.com/growthbook/growthbook-mcp",

package/server/tools/defaults.js

@@ -1,4 +1,4 @@
-import { handleResNotOk, fetchWithRateLimit, } from "../utils.js";
+import { handleResNotOk, fetchWithRateLimit, buildHeaders, } from "../utils.js";
 import envPaths from "env-paths";
 import { writeFile, readFile, mkdir, unlink } from "fs/promises";
 import { join } from "path";
@@ -10,18 +10,14 @@ const userDefaultsFile = join(experimentDefaultsDir, "user-defaults.json");
 export async function createDefaults(apiKey, baseApiUrl) {
     try {
         const experimentsResponse = await fetchWithRateLimit(`${baseApiUrl}/api/v1/experiments`, {
-            headers: {
-                Authorization: `Bearer ${apiKey}`,
-            },
+            headers: buildHeaders(apiKey, false),
         });
         await handleResNotOk(experimentsResponse);
         const experimentData = await experimentsResponse.json();
         if (experimentData.experiments.length === 0) {
             // No experiments: return assignment query and environments if possible
             const assignmentQueryResponse = await fetchWithRateLimit(`${baseApiUrl}/api/v1/data-sources`, {
-                headers: {
-                    Authorization: `Bearer ${apiKey}`,
-                },
+                headers: buildHeaders(apiKey, false),
             });
             await handleResNotOk(assignmentQueryResponse);
             const dataSourceData = await assignmentQueryResponse.json();
@@ -30,9 +26,7 @@ export async function createDefaults(apiKey, baseApiUrl) {
             }
             const assignmentQuery = dataSourceData.dataSources[0].assignmentQueries[0].id;
             const environmentsResponse = await fetchWithRateLimit(`${baseApiUrl}/api/v1/environments`, {
-                headers: {
-                    Authorization: `Bearer ${apiKey}`,
-                },
+                headers: buildHeaders(apiKey, false),
             });
             await handleResNotOk(environmentsResponse);
             const environmentsData = await environmentsResponse.json();
@@ -55,10 +49,7 @@ export async function createDefaults(apiKey, baseApiUrl) {
         if (experimentData.hasMore) {
             const mostRecentExperiments = await fetchWithRateLimit(`${baseApiUrl}/api/v1/experiments?offset=${experimentData.total -
                 Math.min(50, experimentData.count + experimentData.offset)}&limit=${Math.min(50, experimentData.count + experimentData.offset)}`, {
-                headers: {
-                    Authorization: `Bearer ${apiKey}`,
-                    "Content-Type": "application/json",
-                },
+                headers: buildHeaders(apiKey),
             });
             await handleResNotOk(mostRecentExperiments);
             const mostRecentExperimentData = await mostRecentExperiments.json();
@@ -113,9 +104,7 @@ export async function createDefaults(apiKey, baseApiUrl) {
         }
         // Fetch environments
         const environmentsResponse = await fetchWithRateLimit(`${baseApiUrl}/api/v1/environments`, {
-            headers: {
-                Authorization: `Bearer ${apiKey}`,
-            },
+            headers: buildHeaders(apiKey, false),
         });
         await handleResNotOk(environmentsResponse);
         const environmentsData = await environmentsResponse.json();

package/server/tools/environments.js

@@ -1,4 +1,4 @@
-import { handleResNotOk, fetchWithRateLimit, } from "../utils.js";
+import { handleResNotOk, fetchWithRateLimit, buildHeaders, } from "../utils.js";
 import { z } from "zod";
 /**
  * Tool: get_environments
@@ -14,10 +14,7 @@ export function registerEnvironmentTools({ server, baseApiUrl, apiKey, }) {
     }, async () => {
         try {
             const res = await fetchWithRateLimit(`${baseApiUrl}/api/v1/environments`, {
-                headers: {
-                    Authorization: `Bearer ${apiKey}`,
-                    "Content-Type": "application/json",
-                },
+                headers: buildHeaders(apiKey),
             });
             await handleResNotOk(res);
             const data = await res.json();

package/server/tools/experiments/experiment-summary.js

@@ -1,4 +1,4 @@
-import { fetchWithRateLimit, handleResNotOk } from "../../utils.js";
+import { fetchWithRateLimit, handleResNotOk, buildHeaders } from "../../utils.js";
 import { computeVerdict, formatLift, getYearMonth, median, round, } from "./summary-logic.js";
 // Metric Lookup with caching
 const metricCache = new Map();
@@ -48,10 +48,7 @@ async function getMetricLookup(baseApiUrl, apiKey, metricIds) {
         const regularResults = await processBatch(regularMetricIds, MAX_CONCURRENT_FETCHES, async (metricId) => {
             try {
                 const res = await fetchWithRateLimit(`${baseApiUrl}/api/v1/metrics/${metricId}`, {
-                    headers: {
-                        Authorization: `Bearer ${apiKey}`,
-                        "Content-Type": "application/json",
-                    },
+                    headers: buildHeaders(apiKey),
                 });
                 await handleResNotOk(res);
                 const data = await res.json();
@@ -74,10 +71,7 @@ async function getMetricLookup(baseApiUrl, apiKey, metricIds) {
         const factResults = await processBatch(factMetricIds, MAX_CONCURRENT_FETCHES, async (metricId) => {
             try {
                 const res = await fetchWithRateLimit(`${baseApiUrl}/api/v1/fact-metrics/${metricId}`, {
-                    headers: {
-                        Authorization: `Bearer ${apiKey}`,
-                        "Content-Type": "application/json",
-                    },
+                    headers: buildHeaders(apiKey),
                 });
                 await handleResNotOk(res);
                 const data = await res.json();

package/server/tools/experiments/experiments.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { generateLinkToGrowthBook, getDocsMetadata, handleResNotOk, SUPPORTED_FILE_EXTENSIONS, paginationSchema, fetchWithRateLimit, fetchWithPagination, featureFlagSchema, fetchFeatureFlag, mergeRuleIntoFeatureFlag, } from "../../utils.js";
+import { generateLinkToGrowthBook, getDocsMetadata, handleResNotOk, SUPPORTED_FILE_EXTENSIONS, paginationSchema, fetchWithRateLimit, fetchWithPagination, featureFlagSchema, fetchFeatureFlag, mergeRuleIntoFeatureFlag, buildHeaders, } from "../../utils.js";
 import { getDefaults } from "../defaults.js";
 import { handleSummaryMode } from "./experiment-summary.js";
 export function registerExperimentTools({ server, baseApiUrl, apiKey, appOrigin, user, }) {
@@ -31,10 +31,7 @@ export function registerExperimentTools({ server, baseApiUrl, apiKey, appOrigin,
         if (experimentId) {
             try {
                 const res = await fetchWithRateLimit(`${baseApiUrl}/api/v1/experiments/${experimentId}`, {
-                    headers: {
-                        Authorization: `Bearer ${apiKey}`,
-                        "Content-Type": "application/json",
-                    },
+                    headers: buildHeaders(apiKey),
                 });
                 await handleResNotOk(res);
                 const data = await res.json();
@@ -45,9 +42,7 @@ export function registerExperimentTools({ server, baseApiUrl, apiKey, appOrigin,
                     }
                     try {
                         const resultsRes = await fetchWithRateLimit(`${baseApiUrl}/api/v1/experiments/${experimentId}/results`, {
-                            headers: {
-                                Authorization: `Bearer ${apiKey}`,
-                            },
+                            headers: buildHeaders(apiKey, false),
                         });
                         await handleResNotOk(resultsRes);
                         const resultsData = await resultsRes.json();
@@ -104,9 +99,7 @@ export function registerExperimentTools({ server, baseApiUrl, apiKey, appOrigin,
                     }
                     try {
                         const resultsRes = await fetchWithRateLimit(`${baseApiUrl}/api/v1/experiments/${experiment.id}/results`, {
-                            headers: {
-                                Authorization: `Bearer ${apiKey}`,
-                            },
+                            headers: buildHeaders(apiKey, false),
                         });
                         await handleResNotOk(resultsRes);
                         const resultsData = await resultsRes.json();
@@ -160,10 +153,7 @@ export function registerExperimentTools({ server, baseApiUrl, apiKey, appOrigin,
             const queryParams = new URLSearchParams();
             queryParams.append("limit", "100");
             const res = await fetchWithRateLimit(`${baseApiUrl}/api/v1/attributes?${queryParams.toString()}`, {
-                headers: {
-                    Authorization: `Bearer ${apiKey}`,
-                    "Content-Type": "application/json",
-                },
+                headers: buildHeaders(apiKey),
             });
             await handleResNotOk(res);
             const data = await res.json();
@@ -258,10 +248,7 @@ export function registerExperimentTools({ server, baseApiUrl, apiKey, appOrigin,
         try {
             const experimentRes = await fetchWithRateLimit(`${baseApiUrl}/api/v1/experiments`, {
                 method: "POST",
-                headers: {
-                    Authorization: `Bearer ${apiKey}`,
-                    "Content-Type": "application/json",
-                },
+                headers: buildHeaders(apiKey),
                 body: JSON.stringify(experimentPayload),
             });
             await handleResNotOk(experimentRes);
@@ -283,10 +270,7 @@ export function registerExperimentTools({ server, baseApiUrl, apiKey, appOrigin,
                 const flagPayload = mergeRuleIntoFeatureFlag(existingFeature, newRule, experimentDefaults.environments);
                 const flagRes = await fetchWithRateLimit(`${baseApiUrl}/api/v1/features/${featureId}`, {
                     method: "POST",
-                    headers: {
-                        Authorization: `Bearer ${apiKey}`,
-                        "Content-Type": "application/json",
-                    },
+                    headers: buildHeaders(apiKey),
                     body: JSON.stringify(flagPayload),
                 });
                 await handleResNotOk(flagRes);

package/server/tools/features.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { getDocsMetadata, handleResNotOk, generateLinkToGrowthBook, paginationSchema, featureFlagSchema, fetchWithRateLimit, fetchWithPagination, fetchFeatureFlag, mergeRuleIntoFeatureFlag, } from "../utils.js";
+import { getDocsMetadata, handleResNotOk, generateLinkToGrowthBook, paginationSchema, featureFlagSchema, fetchWithRateLimit, fetchWithPagination, fetchFeatureFlag, mergeRuleIntoFeatureFlag, buildHeaders, } from "../utils.js";
 import { exec } from "child_process";
 import { getDefaults } from "./defaults.js";
 export function registerFeatureTools({ server, baseApiUrl, apiKey, appOrigin, user, }) {
@@ -23,10 +23,7 @@ export function registerFeatureTools({ server, baseApiUrl, apiKey, appOrigin, us
         }
         else {
             const envRes = await fetchWithRateLimit(`${baseApiUrl}/api/v1/features/environments`, {
-                headers: {
-                    Authorization: `Bearer ${apiKey}`,
-                    "Content-Type": "application/json",
-                },
+                headers: buildHeaders(apiKey),
             });
             await handleResNotOk(envRes);
             const envData = await envRes.json();
@@ -51,10 +48,7 @@ export function registerFeatureTools({ server, baseApiUrl, apiKey, appOrigin, us
         try {
             const res = await fetchWithRateLimit(`${baseApiUrl}/api/v1/features`, {
                 method: "POST",
-                headers: {
-                    Authorization: `Bearer ${apiKey}`,
-                    "Content-Type": "application/json",
-                },
+                headers: buildHeaders(apiKey),
                 body: JSON.stringify(payload),
             });
             await handleResNotOk(res);
@@ -123,10 +117,7 @@ export function registerFeatureTools({ server, baseApiUrl, apiKey, appOrigin, us
             const payload = mergeRuleIntoFeatureFlag(existingFeature, newRule, defaultEnvironments);
             const res = await fetchWithRateLimit(`${baseApiUrl}/api/v1/features/${featureId}`, {
                 method: "POST",
-                headers: {
-                    Authorization: `Bearer ${apiKey}`,
-                    "Content-Type": "application/json",
-                },
+                headers: buildHeaders(apiKey),
                 body: JSON.stringify(payload),
             });
             await handleResNotOk(res);
@@ -134,7 +125,7 @@ export function registerFeatureTools({ server, baseApiUrl, apiKey, appOrigin, us
             const linkToGrowthBook = generateLinkToGrowthBook(appOrigin, "features", featureId);
             const { docs, language, stub } = getDocsMetadata(fileExtension);
             const text = `This is the API response: ${JSON.stringify(data)}
-      
+
         Additionally, here is a template of what to show to the user:
 
         **✅ Your feature flag \`my-flag-name\` is ready!.**
@@ -175,10 +166,7 @@ export function registerFeatureTools({ server, baseApiUrl, apiKey, appOrigin, us
         if (featureFlagId) {
             try {
                 const res = await fetchWithRateLimit(`${baseApiUrl}/api/v1/features/${featureFlagId}`, {
-                    headers: {
-                        Authorization: `Bearer ${apiKey}`,
-                        "Content-Type": "application/json",
-                    },
+                    headers: buildHeaders(apiKey),
                 });
                 await handleResNotOk(res);
                 const data = await res.json();
@@ -233,10 +221,7 @@ ask if they want to remove references to the feature flag from the codebase.
                 offset: offset?.toString(),
             });
             const res = await fetchWithRateLimit(`${baseApiUrl}/api/v1/features?${queryParams.toString()}`, {
-                headers: {
-                    Authorization: `Bearer ${apiKey}`,
-                    "Content-Type": "application/json",
-                },
+                headers: buildHeaders(apiKey),
             });
             await handleResNotOk(res);
             const data = await res.json();

package/server/tools/metrics.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { generateLinkToGrowthBook, handleResNotOk, paginationSchema, fetchWithRateLimit, fetchWithPagination, } from "../utils.js";
+import { generateLinkToGrowthBook, handleResNotOk, paginationSchema, fetchWithRateLimit, fetchWithPagination, buildHeaders, } from "../utils.js";
 export function registerMetricsTools({ server, baseApiUrl, apiKey, appOrigin, }) {
     /**
      * Tool: get_metrics
@@ -27,18 +27,12 @@ export function registerMetricsTools({ server, baseApiUrl, apiKey, appOrigin, })
                 let res;
                 if (metricId.startsWith("fact__")) {
                     res = await fetchWithRateLimit(`${baseApiUrl}/api/v1/fact-metrics/${metricId}`, {
-                        headers: {
-                            Authorization: `Bearer ${apiKey}`,
-                            "Content-Type": "application/json",
-                        },
+                        headers: buildHeaders(apiKey),
                     });
                 }
                 else {
                     res = await fetchWithRateLimit(`${baseApiUrl}/api/v1/metrics/${metricId}`, {
-                        headers: {
-                            Authorization: `Bearer ${apiKey}`,
-                            "Content-Type": "application/json",
-                        },
+                        headers: buildHeaders(apiKey),
                     });
                 }
                 await handleResNotOk(res);

package/server/tools/sdk-connections.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { handleResNotOk, paginationSchema, fetchWithRateLimit, fetchWithPagination, } from "../utils.js";
+import { handleResNotOk, paginationSchema, fetchWithRateLimit, fetchWithPagination, buildHeaders, } from "../utils.js";
 export function registerSdkConnectionTools({ server, baseApiUrl, apiKey, }) {
     /**
      * Tool: get_sdk_connections
@@ -85,10 +85,7 @@ export function registerSdkConnectionTools({ server, baseApiUrl, apiKey, }) {
         if (!environment) {
             try {
                 const res = await fetchWithRateLimit(`${baseApiUrl}/api/v1/environments`, {
-                    headers: {
-                        Authorization: `Bearer ${apiKey}`,
-                        "Content-Type": "application/json",
-                    },
+                    headers: buildHeaders(apiKey),
                 });
                 await handleResNotOk(res);
                 const data = await res.json();
@@ -115,10 +112,7 @@ export function registerSdkConnectionTools({ server, baseApiUrl, apiKey, }) {
         try {
             const res = await fetchWithRateLimit(`${baseApiUrl}/api/v1/sdk-connections`, {
                 method: "POST",
-                headers: {
-                    Authorization: `Bearer ${apiKey}`,
-                    "Content-Type": "application/json",
-                },
+                headers: buildHeaders(apiKey),
                 body: JSON.stringify(payload),
             });
             await handleResNotOk(res);

package/server/utils.js

@@ -56,6 +56,62 @@ export function getAppOrigin() {
     userAppOrigin = userAppOrigin?.trim().replace(/\/+$/, "");
     return `${userAppOrigin || defaultAppOrigin}`;
 }
+/**
+ * Parses custom HTTP headers from environment variables with the prefix GB_HTTP_HEADER_*
+ * Converts environment variable names to proper HTTP header format:
+ * GB_HTTP_HEADER_X_TENANT_ID -> X-Tenant-ID
+ * GB_HTTP_HEADER_CF_ACCESS_TOKEN -> Cf-Access-Token
+ *
+ * Example usage:
+ * GB_HTTP_HEADER_X_TENANT_ID=abc123 -> { "X-Tenant-ID": "abc123" }
+ * GB_HTTP_HEADER_CF_ACCESS_TOKEN=<token> -> { "Cf-Access-Token": "<token>" }
+ */
+export function getCustomHeaders() {
+    const customHeaders = {};
+    const headerPrefix = "GB_HTTP_HEADER_";
+    for (const [key, value] of Object.entries(process.env)) {
+        if (key.startsWith(headerPrefix) && value) {
+            // Extract the header name part after the prefix
+            const headerNamePart = key.slice(headerPrefix.length);
+            // Convert underscore-separated name to proper HTTP header format
+            // Example: X_TENANT_ID -> X-Tenant-ID, CF_ACCESS_TOKEN -> Cf-Access-Token
+            const headerName = headerNamePart
+                .split("_")
+                .map((part, index) => {
+                // Special handling for common prefixes like X, API, etc.
+                if (part.length === 1 || part === "API" || part === "ID") {
+                    return part;
+                }
+                // Capitalize first letter, lowercase the rest
+                return part.charAt(0).toUpperCase() + part.slice(1).toLowerCase();
+            })
+                .join("-");
+            customHeaders[headerName] = value;
+        }
+    }
+    return customHeaders;
+}
+/**
+ * Builds HTTP headers for GrowthBook API requests, merging required headers
+ * with any custom headers configured via GB_HTTP_HEADER_* environment variables.
+ *
+ * Custom headers are applied first, then required headers (Authorization, Content-Type)
+ * are added. This ensures required headers always take precedence.
+ *
+ * @param apiKey - The GrowthBook API key for authorization
+ * @param includeContentType - Whether to include Content-Type header (default: true)
+ * @returns Headers object ready for fetch requests
+ */
+export function buildHeaders(apiKey, includeContentType = true) {
+    const headers = {
+        ...getCustomHeaders(),
+        Authorization: `Bearer ${apiKey}`,
+    };
+    if (includeContentType) {
+        headers["Content-Type"] = "application/json";
+    }
+    return headers;
+}
 export function getDocsMetadata(extension) {
     switch (extension) {
         case ".tsx":
@@ -372,10 +428,7 @@ export async function fetchWithRateLimit(url, options, retries = 3) {
  */
 export async function fetchFeatureFlag(baseApiUrl, apiKey, featureId) {
     const res = await fetchWithRateLimit(`${baseApiUrl}/api/v1/features/${featureId}`, {
-        headers: {
-            Authorization: `Bearer ${apiKey}`,
-            "Content-Type": "application/json",
-        },
+        headers: buildHeaders(apiKey),
     });
     await handleResNotOk(res);
     const data = await res.json();
@@ -432,20 +485,14 @@ export async function fetchWithPagination(baseApiUrl, apiKey, endpoint, limit, o
             });
         }
         const res = await fetchWithRateLimit(`${baseApiUrl}${endpoint}?${queryParams.toString()}`, {
-            headers: {
-                Authorization: `Bearer ${apiKey}`,
-                "Content-Type": "application/json",
-            },
+            headers: buildHeaders(apiKey),
         });
         await handleResNotOk(res);
         return await res.json();
     }
     // Most recent behavior: fetch total count first, then calculate offset
     const countRes = await fetchWithRateLimit(`${baseApiUrl}${endpoint}?limit=1`, {
-        headers: {
-            Authorization: `Bearer ${apiKey}`,
-            "Content-Type": "application/json",
-        },
+        headers: buildHeaders(apiKey),
     });
     await handleResNotOk(countRes);
     const countData = await countRes.json();
@@ -464,10 +511,7 @@ export async function fetchWithPagination(baseApiUrl, apiKey, endpoint, limit, o
         });
     }
     const mostRecentRes = await fetchWithRateLimit(`${baseApiUrl}${endpoint}?${mostRecentQueryParams.toString()}`, {
-        headers: {
-            Authorization: `Bearer ${apiKey}`,
-            "Content-Type": "application/json",
-        },
+        headers: buildHeaders(apiKey),
     });
     await handleResNotOk(mostRecentRes);
     return await mostRecentRes.json();