---
name: badgerlytics-management
description: Make changes in Badgerlytics with the Management MCP server, such as creating custom events, funnels, audience traits, SaaS plans and usage items, or creating and running feature flags and A/B tests. Use when the user asks to set up tracking, launch, stop or roll back a test or flag, or tidy up their Badgerlytics configuration.
---

# Badgerlytics Management

The `badgerlytics-management` MCP server changes live configuration for one Badgerlytics organization. It enforces the same rules as the dashboard, and every error says what to fix.

## Never handle the API key

- This server needs a key with the **Management (MCP)** scope. If it replies that the key isn't allowed here, the user needs a new key from Settings → API Keys with that scope ticked — scopes can't be changed on an existing key.
- The key is already configured in the MCP client. Never ask the user for it, never print it, never pass it as a tool argument (calls containing a key are rejected).
- Authentication problems: tell the user to check the `BADGERLYTICS_API_KEY` environment variable and restart their tool. See https://badgerlytics.com/docs#mcp.

## Before changing anything

1. Get the organization and property IDs from the connection instructions, or from `whoami` / `list_properties` (lookups, which have a looser rate limit).
2. Every other tool needs **both** `organizationId` and `propertyId`. If the user's request could apply to more than one property (for example production and staging), ask which one.
3. Look before you create: call the matching `list_*` tool first so you don't create duplicates and so you use the existing tokens.
4. **Confirm with the user before** starting, stopping, restarting or archiving a test or flag, using the kill switch, deleting a draft flag or audience trait, or archiving events, funnels, plans or usage items. Say exactly what will change and on which property.
5. Rate limit: per organization, per server, per minute — 20 change calls and 50 lookups (`whoami`, `list_*`). It's shared by the whole team, so batch your thinking, not your calls. Each call gets 15 seconds.

## Catalog items

- **Custom events:** `create_custom_event` with a name, the event type and how it's triggered. The token is generated from the name; tell the user the token so their developers can fire it. `archive_custom_event` / `unarchive_custom_event` use the event token. Unarchiving counts toward the plan's event limit.
- **Funnels:** `create_funnel` with a name and ordered step names. Tokens come from the names, and a token already used by another funnel (active or archived) is rejected. Unarchive the old funnel instead. `archive_funnel` / `unarchive_funnel` use the funnel token.
- **Audience traits:** `create_audience_trait` with a label (the key is generated, and some keys are reserved). `delete_audience_trait` by key. Deleting can affect flags whose audience uses that trait, so check `list_feature_flags` with `status: "all"` first.
- **SaaS plans and usage items** (SaaS properties only): `create_saas_plan`, `create_usage_item`, and archive/unarchive by code. Codes are generated from names and must be unique, including archived ones.

## Feature flags and A/B tests

Two types: `experiment` (A/B test with variations and a goal) and `flag` (on/off rollout by percentage).

Lifecycle: **draft → running → stopped**, with **archived** as a filed-away stopped flag.

`list_feature_flags` returns **running** flags only unless you ask for more: `status: "draft"` or `"stopped"` for one other state, `status: "all"` for every unarchived flag, `test_token` for one flag, or `include_archived: true` to include archived ones.

| Status | Allowed |
| --- | --- |
| Draft | Edit anything (`update_feature_flag`). `start_feature_flag`. `delete_feature_flag`. Can't archive or use the kill switch. |
| Running | Change weights (fixed-weight tests), `rollout_percent` (flags), focus pages, audience, description. `stop_feature_flag`. Kill switch. Name, type, goal, optimization mode and variations are locked. |
| Stopped | `restart_feature_flag` (starts a new iteration). `archive_feature_flag`. Kill switch. |
| Archived | `unarchive_feature_flag` only. It must be unarchived before it can restart. |

Rules worth knowing:

- Experiments need a `test_description` (the hypothesis) before they can start.
- The goal is an active custom event, `conversion_rate`, or `avg_order_value`. On/off flags have no goal, variations, focus pages or audience.
- The first variation is the control. `weights` must list every variation token and add up to 100.
- Starting counts toward the plan's running-test limit. If it's full, the error says so. Offer to stop another test, but don't do it without confirmation.
- Stopping an experiment requires `winning_variation_token`. Ask the user which variation won, and use `badgerlytics-reports` (`test_summary`) to inform them. Don't pick a winner yourself.
- The kill switch (`set_feature_flag_kill_switch`, `engaged: true`) serves everyone the control experience immediately. It's the fastest rollback. Releasing it (`engaged: false`) returns visitors to their normal variations.

## After a change

Report what changed, on which property, and any token or code the user's developers need. Link them to https://badgerlytics.com/docs for the matching tracking-code setup when they've just created an event, funnel or flag.