How to use GrowthBook's MCP server to clean up stale feature flags before they become tech debt

The dangerous part of stale-flag cleanup is not finding an old key. It is proving which behavior is live, where the key is used, and what depends on it before removal.

Feature flags create temporary branches in code and the control plane. Once a rollout settles, those branches stop providing optionality and start consuming attention. Engineers must remember which path is canonical, tests must cover states that may no longer occur, and future targeting changes can reactivate behavior nobody expects.

GrowthBook's current MCP server can coordinate a reviewable cleanup from an AI coding client. The official flag-search skill finds and classifies candidates. flag-graph traces dependencies and linked experiments. flag-cleanup walks through behavior analysis, code references, inlining, archive, verification, and deletion.

This is not a bulk-delete automation. The safe workflow uses a broad read-only audit followed by one-flag-at-a-time cleanup.

Start with GrowthBook's stale classification

Age is a useful signal but a poor verdict. A six-month-old operational kill switch may be intentional. A three-week-old release flag that sends everyone to the treatment may already be cleanup-ready.

The current flag-search workflow fetches the complete key inventory, then sends explicit IDs to GrowthBook's stale-feature endpoint. GrowthBook returns a reason for each flag:

GrowthBook's current definition treats a flag as stale only after it has gone two weeks without updates and either has no active environments or routes all traffic to one variation. The GrowthBook feature flag release describes the stale and ambiguous categories added for agent workflows.

Ask for an audit, not a cleanup:

Read the latest flag-search skill. Audit all flags in project checkout using GrowthBook's stale endpoint. Group cleanup candidates, excluded never-stale flags, active flags, dependencies, experiments, and drafts. Include IDs, owners, last update, environment state, stale reason, default, and likely settled value. Do not write anything.

The agent should paginate the detailed feature list when needed and respect the API rate limit. It should not manufacture its own “older than 30 days means delete” rule.

Prioritize by risk and confidence

Not every candidate deserves the same treatment. Rank with two axes:

• Confidence in the replacement behavior: Do all users get one known value, or are conditions and temporary rollouts still involved?
• Risk of removal: How many repositories, dependencies, experiments, environments, and critical paths reference the flag?

A disabled test flag with no code references is high-confidence and low-risk. A one-sided checkout flag used as a prerequisite by several other flags is high-confidence about its value but high-risk to remove. An old percentage rollout is low-confidence because some users still receive different behavior.

Practitioner research on feature toggle practices identifies cleanup as a distinct management discipline, not an afterthought. Recent community reports of feature flag debt describe the same failure mode: temporary branches become a new form of permanent complexity.

Turn the audit into a small queue:

P0: incorrect or dangerous live state—stabilize, do not delete
P1: no references, no dependencies, no experiments, one known value
P2: code refs found; straightforward one-value inlining
P3: dependencies, temporary rollout, holdout, or multi-repo work
Excluded: never-stale operational controls

Then choose one P1 or P2 candidate for the first end-to-end run.

Trace the blast radius before editing

flag-graph answers four questions:

1. Which feature-level prerequisites does this flag depend on?
2. Which rule-level prerequisites does it depend on?
3. Which other flags depend on it?
4. Which experiments and holdouts reference it?

Forward dependencies are visible on the target flag. Reverse dependencies require a complete scan because GrowthBook has no single reverse-prerequisite endpoint. The workflow paginates all flags and checks both feature- and rule-level prerequisites. On a large organization, that is an O(n) read and should include a timestamp.

Use this prompt:

Run the latest flag-graph workflow for old-checkout-layout. Trace forward prerequisites one level, scan all flags for reverse dependencies, fetch every linked experiment, and report holdout associations. Give me a safe-to-delete verdict with the scan timestamp. Read only.

A running experiment is a hard stop. A stopped experiment with temporary rollout is not a blocker, but it changes which value is live. A draft experiment using the flag deserves a warning because deletion can prevent it from launching.

Do not treat an empty reverse scan as timeless proof. Another actor can create a dependency after the scan. Re-read state immediately before archive.

Stop flag debt at the source

Put ownership, expected lifetime, and cleanup evidence into the release workflow before temporary conditions spread across the codebase.

Read the Flag Scale Guide

Compute the effective replacement value

Archiving a flag stops every rule from evaluating. Callers receive the flag's default value. That makes the default the usual inline replacement—but not always.

The cleanup skill inspects every rule that diverges from the default:

• a force rule that serves another value to a segment
• a rollout with nonzero coverage
• an experiment rule assigning multiple variations
• a stopped experiment with a temporary winner rollout

The temporary-rollout case is easy to miss. If GrowthBook currently routes all eligible users to a released winner, the live application behavior may be the winner even when the flag default is control. Inlining the default would roll back the feature during “cleanup.”

Require a behavior table:

For old-checkout-layout, compute the value users receive today. Check default, environment enablement, ordered rules, conditions, saved groups, rollout coverage, linked experiment status, temporary rollout, and released variation. Show every audience that differs from the post-archive default. Stop if cleanup changes behavior.

The table should look like:

This is the load-bearing review. Do not move to code edits until the user confirms the intended permanent behavior.

Find every code reference

The cleanup workflow first checks GrowthBook Code References. The GrowthBook Code References guide describes a CI-based scanner that records repository, branch, file, and line context.

Code References are useful but point-in-time. An empty result can mean the flag is unused, the scanner is not configured, the scan is stale, or the relevant repository is missing. It does not prove absence.

If the API returns no references, the agent must confirm the local working directory before searching. Then use an exact key search while excluding vendor, build, generated, and dependency directories. Look beyond direct SDK calls:

• wrappers and typed flag maps
• tests and fixtures
• server and client implementations
• infrastructure or edge code
• mobile repositories
• documentation and runbooks
• telemetry dashboards or event names

Ask:

List GrowthBook Code References for old-checkout-layout, including repo and branch. Compare them with an exact search of this confirmed repository. Group by file, mark likely production, test, generated, and documentation references, and report any mismatch. Do not edit.

If multiple repositories consume the same flag, do not archive after cleaning only the current repository.

Inline behavior one file at a time

The agent should read each file in full and propose one coherent edit per file. Replacing the flag call mechanically is not enough. Remove the obsolete branch and simplify surrounding code.

For example, this:

const showNew = growthbook.isOn("old-checkout-layout");
return showNew ? <NewCheckout /> : <LegacyCheckout />;

might become:

return <NewCheckout />;

Then remove dead imports, tests for unreachable control behavior, obsolete fixtures, and event dimensions that only served the experiment. Preserve shared utilities that other flags still use.

Run the narrowest relevant tests after each file group, then the project's broader checks. Record skipped files and unresolved references. Do not let “the build passes” replace runtime verification if the flag affects configuration, background jobs, or a separate deployed service.

The GrowthBook feature flag docs remain the source for how defaults and rules evaluate. General engineering guidance such as Martin Fowler's feature toggle article reinforces why release toggles should be removed once their decision is settled.

Archive before deleting

Archive is the reversible production test. The cleanup workflow re-fetches state, checks for unresolved drafts, then archives through GrowthBook's revision-and-publish path. Approval and merge-conflict policies still apply.

Ask:

Re-run the safety checks for old-checkout-layout. Confirm no running experiment, no active draft, no never-stale protection, no new dependency, and no unreviewed behavior divergence. Archive the flag only after I confirm. Do not delete.

After archive:

• deploy the code cleanup
• exercise affected flows
• watch errors and relevant product metrics
• confirm all repositories are on the cleaned version
• rescan for code references
• verify GrowthBook reports the flag as archived

Because archive disables rule evaluation, this period tests the exact post-cleanup control-plane behavior. If something breaks, unarchive while investigating.

Delete only after a separate verification cycle

Permanent deletion removes the feature and all revisions. The current skill therefore stops between archive and delete even if the operator initially asked to “remove” the flag.

Use a second, explicit prompt after verification:

We deployed the code cleanup, ran tests, verified production, and rescanned all repositories. Re-fetch old-checkout-layout and its dependency graph. If it is still archived and no new blockers exist, show the irreversible delete action and wait for my confirmation.

GrowthBook may require an organization-wide REST API bypass setting for deletion. A token-level review bypass can authorize archive without authorizing permanent delete. If the API refuses, leave the flag archived and use an approved admin path. Never recreate or bypass the archive to work around policy.

Deleting a flag unlinks experiments but does not delete those experiments. Their tracking keys may now refer to a nonexistent flag. Holdout relationships can also require manual review. Include those follow-ups in the receipt.

Use a cleanup receipt

Every completed cleanup should record:

Flag: old-checkout-layout
Stale reason: rules-one-sided
Settled behavior: true
Dependencies: none at <timestamp>
Experiments: stopped; temporary rollout winner=true
Code references: 8 across 3 files and 1 repository
Inline changes: <commit>
Tests/build: <commands and results>
Archived: revision <n>, <timestamp>
Production verification: <evidence>
Deleted: <timestamp and actor> OR retained archived
Remaining follow-ups: experiment tracking key, holdout, docs, code-ref rescan

Schedule the read-only audit weekly or monthly, but keep mutation per flag. Community threads about cleanup ownership consistently point to the same organizational issue: dashboards can identify debt, but a named owner and an enforced done definition remove it.

Prevention is cheaper than recovery. Apply the ownership and expiration practices in GrowthBook's feature flag best-practices guide when a flag is created, and close monitored release work using the same evidence recorded by safe rollouts. A cleanup owner should be able to trace the release decision without interviewing the original author months later.

The GrowthBook feature flags platform gives teams the state, audit trail, and code-reference hooks. MCP reduces the work of joining those signals with a live codebase. The safe sequence—classify, trace, compute, inline, archive, verify, delete—keeps cleanup from becoming its own production incident.

Make cleanup part of shipping

Adopt a feature flag operating model that defines ownership and retirement before temporary release logic becomes permanent tech debt.

Build the Cleanup Habit