How to use GrowthBook's MCP server to ship a feature behind a flag without leaving your editor

The safest editor-native feature launch starts with the current experience as the default and ends with a verified live revision—not with “turn this on.”

GrowthBook's MCP server lets a compatible AI coding client read and update feature flag configuration while it also works with your repository. That removes the repetitive loop of creating a key in a dashboard, copying it into code, returning to the dashboard for a rule, and then reconstructing what changed.

The current server uses a thin, open-source API bridge and official agent skills. It exposes three top-level tools, while workflow knowledge lives in versioned skills such as flag-create, flag-targeting, flag-ramp, flag-monitoring, and flag-publish. You can inspect that architecture in the GrowthBook MCP repository and the current GrowthBook skills catalog.

The editor is a useful control surface, but it is not a reason to collapse deployment, exposure, and approval into one opaque prompt. Keep those states separate and require a receipt after each.

Understand the two changes you are making

“Ship behind a flag” combines a code change and a control-plane change.

MCP standardizes the second path for an AI client. The MCP server concepts guide explains how tools expose actions, while the coding client uses its normal file and terminal capabilities for the first path.

This separation makes failures easier to reason about. If the code has not deployed, a valid GrowthBook rule cannot create the treatment. If the flag remains disabled, deployed treatment code stays dark. If the SDK never receives the targeting attribute, a syntactically valid audience condition never matches.

Before starting, connect MCP with a token scoped to the relevant GrowthBook project. The GrowthBook MCP setup page covers compatible clients. For self-hosted GrowthBook, point GB_API_URL at the instance rather than relying on the cloud default.

Step 1: Describe the flag contract

A good request names the behavior, not just the UI component. Include:

• permanent kebab-case key
• project
• owner or owning team
• value type
• safe default
• environments
• initial audience
• expected lifetime and cleanup condition

For example:

Gate the new billing summary behind a Boolean flag named new-billing-summary in project billing. False must preserve the current summary. The flag should start disabled in every environment and have no rules. The owning team is Billing Platform; cleanup begins after the feature is fully rolled out and the old renderer is removed.

Feature keys cannot be renamed after creation, so resist temporary ticket IDs. A Boolean is appropriate for a simple branch. A string supports named modes. A number or JSON object is remote configuration and deserves runtime validation.

Ask the agent to perform a read-only collision and scope check first:

Read the latest flag-create skill. Confirm the key is unused, resolve project billing, list all environment IDs, and show the proposed payload. Do not create the flag yet.

The skill checks all existing feature keys and builds an explicit environment map. It does not rely on the organization's default setting for new environments.

The reviewed create body should be concrete before the mutation. Replace the IDs with values returned by the project and environment reads:

{
  "id": "new-billing-summary",
  "valueType": "boolean",
  "defaultValue": "false",
  "description": "Gate the new billing summary renderer",
  "environments": {
    "production": { "enabled": false },
    "staging": { "enabled": false }
  },
  "project": "<BILLING_PROJECT_ID>"
}

defaultValue is a string even for a Boolean flag. Include every environment explicitly and omit rules from the create payload; targeting belongs in a later draft revision.

Step 2: Create the disabled flag

After reviewing the key, type, default, and project, authorize only the create operation:

Create new-billing-summary with the reviewed payload. Keep every environment disabled. After the POST, fetch the flag and report its ID, type, default, environment states, rules count, owner, project, and GrowthBook link. Do nothing else.

The expected receipt is boring: disabled everywhere, zero rules, default "false". That is a good starting state. If the agent reports any enabled environment or existing rule, stop before editing code and investigate.

The current v2 workflow differs from early GrowthBook MCP examples that named a fixed create_feature_flag tool. The server can still create the flag, but it does so after loading flag-create and calling the REST API. Old community posts such as the original GrowthBook MCP announcement are useful history, not a current tool contract.

Step 3: Add the evaluation in code

Now ask the coding agent to inspect the repository before editing:

Find the existing GrowthBook SDK initialization and feature-evaluation conventions in this repository. Show where the billing summary chooses its renderer. Propose the smallest change that uses new-billing-summary, with false as the existing behavior. Add tests for false, true, and missing configuration. Do not change GrowthBook.

The implementation should use the installed SDK documented in the GrowthBook SDK guides, not a second client or a hand-written fetch to the feature endpoint. Reuse the existing attributes and tracking lifecycle.

A strong code review checks:

• the false or fallback branch is the current production behavior
• evaluation occurs only where both branches have enough context
• the SDK instance is not recreated for every component render
• server and client rendering cannot disagree visibly
• targeting attributes use the same names and types registered in GrowthBook
• evaluation and exposure behavior match the use case
• both branches are covered by tests

Feature flags separate deployment from release, a pattern well documented in Martin Fowler's feature toggle guide. The deployment can include dormant treatment code while GrowthBook continues to serve the control.

For the JavaScript SDK, the application branch can be as small as this. Adapt the component names to the repository, but keep the false branch as the existing behavior:

const showNewSummary = growthbook.isOn("new-billing-summary");

return showNewSummary
  ? renderNewBillingSummary(invoice)
  : renderCurrentBillingSummary(invoice);

Test the branch with an explicit false value, an explicit true value, and missing configuration. Reuse the repository's existing SDK instance; do not instantiate another client around this snippet.

Ship flags that stay manageable

Use durable naming, ownership, rollout, and cleanup conventions before the first production audience sees the feature.

Read the Scale Guide

Step 4: Deploy dark and verify the default path

Merge and deploy the code with the flag still disabled. Confirm that production renders the current billing summary and that no error occurs when the new key is absent or delayed.

Then ask for a read-only GrowthBook check:

Fetch new-billing-summary. Confirm production is disabled, default is false, no rule is live, and there are no open drafts. Also report the latest SDK connection or configuration context relevant to this project if available. Do not change state.

Application SDKs evaluate locally from a feature payload. The OpenFeature specification provides a vendor-neutral description of evaluation concepts such as flags, contexts, and providers. GrowthBook remains the source of truth for the payload and rules.

If your application uses caching, proxying, or streaming updates, verify the refresh behavior in your architecture. Do not promise an absolute propagation time. “Published” and “observed by this specific application instance” are different claims.

Step 5: Add an internal or beta targeting rule

flag-targeting can add either a force rule or a percentage rollout. For the first exposure, prefer a specific audience whose behavior you can observe.

The workflow fetches registered GrowthBook attributes before building a condition. It can also resolve saved groups and rule-level flag prerequisites. These fields can be combined, and all apply together.

For example:

On new-billing-summary, add a production force rule that serves true only to the saved group billing-team. Fetch and show all current rules and the resolved saved-group ID first. Add the rule to a draft, scoped only to production. Stop before publishing.

After the saved-group lookup returns its ID, the draft rule body should look like this:

{
  "rule": {
    "type": "force",
    "value": "true",
    "description": "Billing Platform verification",
    "enabled": true,
    "allEnvironments": false,
    "environments": ["production"],
    "savedGroups": [
      { "ids": ["<BILLING_TEAM_SAVED_GROUP_ID>"], "match": "all" }
    ]
  }
}

The skill posts the payload to /api/v2/features/new-billing-summary/revisions/new/rules and returns a draft revision.version. Keep that version in every later review and publish instruction so the agent cannot silently switch drafts.

Do not assume “employees” is an SDK attribute. It may be a saved group, a Boolean such as isEmployee, or a company-domain condition. The agent should ask when the GrowthBook configuration leaves that ambiguous.

Rule order is another critical check. Rules evaluate top to bottom and the first match wins. New rules append. The receipt should show the full ordered list and explain whether an earlier rule can intercept the intended audience.

The GrowthBook targeting rules documentation is the canonical reference for attributes, conditions, hashing, and evaluation.

Step 6: Review and publish the draft

A write to a draft is not yet a release. Ask for an exact diff:

Inspect the current draft for new-billing-summary. Show base revision, draft version, author, environment scope, ordered rule list, served value, condition or saved groups, and any concurrent live changes. Do not publish.

Then confirm the production action:

Publish revision <version> on new-billing-summary with comment “Enable for Billing Platform verification.” After publishing, fetch the flag again and report live revision, production enabled state, default, and all active rules.

The bundled helper sequence behind the publish request is:

echo '{"comment":"Enable for Billing Platform verification."}' \
  | gb-call POST /api/v2/features/new-billing-summary/revisions/<VERSION>/publish -
gb-call GET /api/v2/features/new-billing-summary

The first response proves the revision transition. The second proves which environment and rules are now live. If the publish returns an approval requirement or a 409 conflict, stop on that branch rather than treating the readback as success.

If approval is required, flag-publish requests a review and stops. The draft author cannot self-approve. If another change reached the flag first, a 409 indicates a merge conflict. The workflow fetches field-level conflicts and asks a human whether each should keep the draft or the newer live value. It never retries blindly.

One subtlety: a rule does nothing when its environment is disabled. If the flag was created off everywhere, production must be enabled through flag-toggle in the same reviewed draft or a separate one. The prompt and receipt should distinguish environment enablement from rule-level enabled.

Step 7: Verify the intended audience

After publish, verify both the GrowthBook state and application behavior:

• a known member of the beta group receives true
• a known non-member receives false
• missing attributes fall through safely
• the expected rule ID matches first
• client logs or debug output identify the expected source
• error, latency, and business telemetry remain healthy

Ask for a read-only configuration explanation:

Explain how new-billing-summary evaluates for these 3 test contexts. Use the live rule order, environment state, and default value. Do not mutate. Identify which rule matches or why evaluation falls through.

The agent can reason over configuration, but the final proof is an evaluation in the application runtime. Community discussions about GrowthBook in self-hosted flag systems often focus on update delivery and local evaluation; your verification should reflect the actual SDK and update mechanism you operate.

Step 8: Expand with a ramp, not a jump

Once the targeted audience is healthy, replace or supplement the narrow rule with a percentage rollout. For coverage below 100%, the rule needs a hash attribute. That attribute should be stable and registered for the project.

Start by staging a rule:

Propose a production rollout rule for new-billing-summary that serves true to 5% of eligible users, hashed by the registered user ID. Show current rule order and how the beta rule interacts with this rollout. Add to the existing draft only.

Then use flag-ramp for a planned progression:

Attach a ramp to the rollout rule: 5%, 25%, 50%, then 100%. Soak for 24 hours at each step and require explicit approval before 50% and 100%. Use the rule's current coverage as the rollback state. Stage only.

If you have suitable warehouse metrics, flag-monitoring can attach guardrails and health actions. The GrowthBook safe rollout docs explain the product model. Configure at least one guardrail on the same datasource as the exposure query.

For a first rollout, use SRM hold rather than automatic rollback, and decide explicitly whether a guardrail failure should roll back automatically. Automatic action is only as sound as the metric, query freshness, and threshold.

Keep a copy-ready release receipt

For every stage, store a compact receipt in the pull request:

Flag: new-billing-summary
Project: billing
Value type/default: boolean / false
Code: <commit>
Tests: false, true, missing configuration
GrowthBook draft: revision 42
Production enabled: yes
Rules: billing-team force=true; rollout 5% hash=id
Ramp: 5 → 25 → 50 → 100; approval at 50 and 100
Monitoring: payment-errors guardrail; SRM=hold
Published by/reviewed by: <identities>
Rollback: disable production or roll ramp to captured start state
Cleanup trigger: 100% stable + old renderer removed

This is what “without leaving your editor” should mean: the IDE contains the code diff, GrowthBook context, review conversation, and evidence. It should not mean skipping the GrowthBook control model.

The GrowthBook feature flags overview connects targeted release, gradual rollout, and experimentation. MCP makes those capabilities accessible where engineers already work. Your team's explicit state transitions make them safe to use.

Build a safer rollout path

Learn how to pair staged exposure with the ownership and cleanup practices that keep release controls useful over time.

Plan the Rollout