Documentation

Everything you need to integrate feature flags into your application. From quick start guides to advanced targeting rules.

/

Quick Start Guide

1

Install the SDK

npm install @buildrflags/sdk
2

Initialize the client

flags.ts
import { BuildrFlags } from '@buildrflags/sdk';

const flags = new BuildrFlags({
  apiKey: 'bf_your_api_key',
  environment: 'production'
});
3

Evaluate a flag

app.ts
const isEnabled = await flags.isEnabled('new-feature', {
  userId: user.id,
  email: user.email
});

if (isEnabled) {
  // Show the new feature
}

That's it!You're now ready to ship features with confidence. Create flags in the dashboard and they'll be available instantly.

SDK Reference

Our TypeScript SDK is designed for simplicity and type safety.

Core Methods

isEnabled(key, context)Check if a boolean flag is enabled
getValue(key, context)Get the value of a flag (any type)
getAllFlags(context)Get all flags for a context
identify(context)Pre-fetch flags for a user context

Built-in Caching

60-second default TTL. Configurable per-flag or globally. Reduces API calls while keeping flags fresh.

Automatic Retries

Exponential backoff on failures. Graceful degradation with fallback values. Your app stays responsive.

REST API

Full API access for custom integrations and automation.

Evaluate a flag
GET /api/sdk/flags/:flagKey/evaluate

# Headers
Authorization: Bearer bf_your_api_key
X-Environment: production

# Query params (context)
?userId=user_123&email=user@example.com
GET/flags

List all flags

POST/flags

Create a flag

PUT/flags/:id

Update a flag

Targeting Rules

Target the right users with precise conditions, segment membership, and rollout percentages.

Common conditions

  • plan equals pro
  • country in [US, CA]
  • user_id starts with beta_
  • created_at greater than 2026-01-01

Rollouts + segments

Combine segments with percentage rollouts to gradually enable features for qualified users.

Example: 25% rollout for the “beta_users” segment in production.

A/B Experiments

Design experiments, split traffic across variants, and analyze outcomes with confidence.

Define variants and weights directly in the dashboard.

Track exposures and conversions to calculate lift.

Pause, iterate, or end experiments based on real-time results.

Segments

Build reusable audiences once and apply them across every flag and experiment.

Why segments?

  • Keep targeting logic consistent across teams.
  • Update one segment and every flag stays in sync.
  • Combine segment membership with custom rules.

Webhooks

PRO

Get real-time notifications when flags change. Use webhooks to trigger CI/CD pipelines, send Slack alerts, or sync any external system.

HMAC-SHA256 signing

Every payload is signed with your secret so you can verify authenticity before processing.

Retry with backoff

Failed deliveries are retried automatically with exponential backoff (up to 5 attempts).

Example payload
{
  "event": "flag.updated",
  "timestamp": "2026-03-28T14:00:00Z",
  "flagKey": "new-checkout",
  "environment": "production",
  "enabled": true,
  "changedBy": "user@example.com"
}

Supported events

flag.createdflag.updatedflag.deletedflag.enabledflag.disabledflag.scheduled
Node.js / TypeScript
import crypto from "crypto";

function verifyWebhook(payload: string, sig: string, secret: string) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(payload)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(sig)
  );
}
Model Context Protocol

MCP Server

The BuildrFlags MCP server lets Claude, Cursor, Windsurf, and any MCP-compatible AI agent manage your feature flags using plain English. Ship features, run health audits, and toggle flags — all from your AI assistant, no dashboard required.

Install

Terminal
npx @buildrflags/mcp

No install step needed — npx runs the latest version on demand. Publish the package once and it stays current automatically.

Configure Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or the equivalent on your OS:

{
  "mcpServers": {
    "buildrflags": {
      "command": "npx",
      "args": ["@buildrflags/mcp"],
      "env": {
        "BUILDRFLAGS_API_KEY": "bf_production_xxxxxxxx",
        "BUILDRFLAGS_WORKSPACE_ID": "ws_xxxxxxxx",
        "BUILDRFLAGS_ENV_KEY": "production"
      }
    }
  }
}

Get your API key from the API Keys page in the dashboard. Your workspace ID and env key are shown in workspace settings.

Available tools

manage_flags

Create, update, toggle, and delete feature flags in one call.

evaluate_flag

Evaluate a flag for a specific user with targeting context.

analyze_flag_health

Audit all flags for staleness, zombie flags, missing descriptions, and rollout issues.

list_segments

Browse reusable audience segments and their targeting rules.

list_experiments

View A/B experiments and their current variant configuration.

get_audit_log

Retrieve a full audit trail of flag changes across your workspace.

Try these prompts in Claude

  • ›"Enable the new-checkout flag for 25% of Pro users in production."
  • ›"Run a flag health audit and list any zombie or stale flags."
  • ›"Create a feature flag called dark-mode and enable it for the beta-users segment."
  • ›"What flags were changed in the last 24 hours? Show me the audit log."

Cursor, Windsurf & more

Any editor or agent that supports MCP works the same way — add the server config above and your AI coding assistant can manage flags inline while you code. No tab-switching, no dashboard.