Windsurf + GrowthBook: AI-native experimentation in Windsurf Editor

Windsurf helps you change code. GrowthBook helps you decide how that code reaches users.

The integration is valuable because it joins two workflows that are usually split: AI-assisted implementation and production release control. Windsurf can read the repository, edit files, and explain the change. GrowthBook can create the flag, control exposure, run the experiment, and show whether the change helped.

This guide explains the practical integration pattern for Windsurf experimentation: connect GrowthBook, create or inspect flags, wrap code, run QA, and graduate the change after measurement.

The integration model

The implementation details below are grounded in Windsurf Cascade MCP docs, Model Context Protocol introduction, and developer discussions about feature flag organization. For GrowthBook-specific steps, use the GrowthBook MCP docs, feature flag docs, and feature flag experiment docs.

The model is simple:

1. Windsurf inspects the codebase and proposes the implementation.
2. GrowthBook provides the flag, targeting rule, metric, or experiment.
3. Windsurf edits code against that known GrowthBook object.
4. Tests and review verify both paths.
5. GrowthBook controls rollout and analysis.

This is different from asking an agent to "add a flag." The flag is not only code. It is a release object with ownership, targeting, defaults, and measurement.

Connect the GrowthBook MCP Server

Use the GrowthBook MCP Server docs for the exact setup path for your client. The server exposes feature flag, experiment, environment, project, SDK connection, metric, and documentation-search tools.

The universal shape is:

{
"mcpServers": {
"growthbook": {
"command": "npx",
"args": ["-y", "@growthbook/mcp@latest"],
"env": {
"GB_API_KEY": "YOUR_API_KEY",
"GB_EMAIL": "YOUR_EMAIL"
}
}
}
}

Some clients use JSON configuration. Claude Code uses a terminal command. Codex can use codex mcp or config.toml. Gemini CLI uses settings.json. VS Code with Copilot uses VS Code MCP configuration.

Create a safe feature flag workflow

A good first workflow is small:

Create a boolean GrowthBook flag named ai_generated_search_empty_state.
Default it to false.
Wrap only the search empty-state component.
Keep the current empty state as fallback.
Add tests for both flag states.
Do not enable the flag in production.

Then review the output for four things:

• The flag key matches the GrowthBook object.
• The fallback path is still present.
• The treatment path is isolated.
• Tests cover both states.

GrowthBook's feature flags page covers rollout control, while the SDK docs cover runtime integration.

Add experiment discipline when the change needs proof

If the feature affects activation, conversion, retention, revenue, or user trust, create an experiment instead of relying on before/after comparison.

Prompt Windsurf this way:

Create an experiment spec for this flag.
Hypothesis: the new empty state increases successful second searches.
Primary metric: second_search_success_rate.
Guardrails: search_error_rate and page_latency.
If any metric is missing in GrowthBook, stop and report the missing metric.

The GrowthBook experimentation platform and feature flag experiment docs support this pattern directly. The agent can help wire the code, but the metric definitions should stay in the system the team trusts.

Use AI for review, not only generation

The best Windsurf + GrowthBook workflow uses the agent twice: once to implement and once to review.

Review prompt:

Review this GrowthBook integration.
Check flag naming, fallback behavior, assignment stability, analytics events, tests, and cleanup notes.
Prioritize issues by severity.
Do not edit files.

That gives the reviewer a concrete surface. It also makes the agent look for release risk, not only syntax errors.

Where GrowthBook fits

GrowthBook gives Windsurf a safer job. Instead of "ship this," the agent gets a narrower instruction: "put this behind a controlled flag, preserve the fallback, and prepare an experiment." That is the right division of labor for AI-native development.

Start with one flag. Then add one experiment. Once the workflow works, put it into team instructions so future AI-generated code follows the same release path.

For broader agent support, compare VS Code MCP configuration, Cursor MCP docs, Gemini CLI MCP docs, GitHub Copilot MCP docs, and the official MCP Registry. These are not substitutes for GrowthBook feature flags or GrowthBook experiments; they are the client-side paths that make those controls available to different agents.

A day-one workflow for Windsurf experimentation

The first useful workflow should fit inside one pull request:

1. Ask Windsurf to inspect existing GrowthBook SDK usage.
2. Create or choose one GrowthBook flag.
3. Implement one isolated treatment behind that flag.
4. Add tests for flag off and flag on.
5. Ask Windsurf to review the diff without editing.
6. Link the pull request to the GrowthBook flag.
7. Turn on the flag only for an internal or sandbox audience.

That sequence gives the AI tool plenty of useful work without handing it the release decision. It also makes the integration visible to normal review. Engineers can inspect code. Product can inspect rollout. Data can inspect the metric plan.

Team instructions to add

Put these rules where Windsurf will read them:

• Use the existing GrowthBook SDK client instead of creating a second client.
• Never remove the fallback path in the first implementation pass.
• Never enable production targeting from code-only instructions.
• Add tests for the default value and the treatment value.
• Return the GrowthBook flag or experiment URL.
• Call out missing metrics instead of inventing metric names.
• Keep unrelated refactors out of the same pull request.

These instructions are intentionally boring. They reduce the space where the agent has to improvise. That is exactly what you want for production release controls.

What good output looks like

A useful Windsurf + GrowthBook run should end with a short summary:

If the agent only returns a code diff, the workflow is incomplete. GrowthBook is there so the change can move through exposure, measurement, and cleanup with the same discipline as implementation.

When to pause the workflow

Pause when Windsurf cannot find the existing SDK integration, when the flag key is unclear, when metrics are missing, or when the diff touches unrelated product behavior. Those are not agent failures. They are signals that the system needs a clearer prompt, a smaller task, or a human decision before code continues.

Practical implementation playbook

Treat windsurf feature flags as a workflow, not a one-off prompt. The teams that get the most value from AI coding tools do three things consistently: they narrow the task, keep release state in GrowthBook, and make the final output reviewable by humans who were not in the original chat.

Step 1: Write the release contract

Before code changes, define the contract in a few sentences:

Change:
User-visible behavior:
GrowthBook flag:
Default value:
Fallback:
Owner:
Primary metric:
Guardrails:
Cleanup condition:

The agent can help fill missing fields, but it should not silently invent them. If the primary metric or owner is missing, the right next step is a gap report.

Step 2: Inspect before editing

Ask the tool to inspect existing patterns first:

• Where does the app initialize the GrowthBook SDK?
• Which helper functions or hooks evaluate flags?
• How are tests written for feature-flagged behavior?
• Where do analytics events fire?
• Which files are likely to change?

This keeps the first implementation from creating a second GrowthBook client, duplicating SDK logic, or placing a flag check too high in the component tree.

Step 3: Make one controlled change

The first pass should be deliberately small. Create or reference one flag, preserve one fallback, and test both states. If the agent discovers a useful refactor, capture it as a separate follow-up. Do not let a flag implementation turn into a cleanup project, design-system rewrite, and analytics migration in the same pull request.

Step 4: Review for release risk

Use the agent again, but switch it into review mode:

Review this AI-assisted change for release risk.
Check flag key consistency, fallback behavior, test coverage, analytics parity, targeting assumptions, and cleanup notes.
List blockers first.
Do not modify files.

This prompt usually finds a different class of issues than normal linting. It looks for the ways a change can be technically valid but operationally unsafe.

Step 5: Expose gradually

Deployment and release should stay separate. Deploy the code with the default safe value. Use GrowthBook to expose the change to internal users, a beta segment, a percentage rollout, or an experiment audience. If the change needs evidence, connect it to an experiment before broad exposure.

Step 6: Close the loop

The workflow is not done when the flag turns on. It is done when one of these outcomes happens:

• The treatment ships and temporary branching logic is removed.
• The treatment loses and the new path is removed.
• The test is inconclusive and the next iteration is defined.
• The rollout is paused because a guardrail or QA issue appeared.

Ask the agent for cleanup only after the human-owned decision is clear.

Example review packet

A good final packet should fit in a pull request comment:

• GrowthBook object: new_checkout_summary flag and linked experiment.
• Default: false for all production users.
• Fallback: existing checkout summary component.
• Treatment: new summary component with revised copy and layout.
• Tests: unit tests for off/on states and one integration smoke test.
• Metrics: checkout completion as primary, error rate and latency as guardrails.
• Rollout: internal staff, beta accounts, then experiment traffic.
• Cleanup: remove losing branch or graduate winning branch after decision.

This packet is not bureaucracy. It is the artifact that lets someone review the work without trusting a chat transcript.