> ## Documentation Index
> Fetch the complete documentation index at: https://confidence.spotify.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Cookbook

> Recipes for common Confidence jobs with the MCP servers: prompts to give your AI assistant, the tools it calls, and how to check the result.

Each recipe in this cookbook covers one job you can do in Confidence by prompting an AI assistant that has the Confidence MCP servers connected. A recipe gives you a prompt to copy, the tools the assistant calls, and a way to check the result.

<Warning>
  The Confidence MCP servers are experimental. Tools and their parameters can change.
</Warning>

## Before You Start

* Connect the servers that a recipe needs. See [MCP Servers](/docs/reference/agent/mcp-servers#integration-setup).
* Replace the example names in each prompt, such as `new-checkout-flow` or `web-client`, with your own.
* The assistant chooses which tools to call. The tool calls listed in each recipe are the typical sequence, not a fixed script.
* Review what the assistant proposes before it changes a flag, rule, or warehouse.

To create or launch an experiment, use the in-app Confidence Agent instead. The MCP servers can only read experiments. See [Work with the Confidence Agent](/docs/guides/work-with-the-confidence-agent).

## Set Up a Client and a Flag with Targeting

**Goal:** Create a client and a flag, and serve a variant to users in one country.

**Server:** [Flags](/docs/reference/agent/mcp-flags)

**Prompt:**

```text theme={null}
Create a Frontend client called web-client. Then create a boolean flag
called new-checkout-flow with variants "on" (enabled: true) and "off"
(enabled: false), and enable it for web-client. Add a targeting rule that
gives users in Sweden 50% "on" and 50% "off". Use the country attribute.
```

**What the assistant does:**

1. `listClients` to check whether `web-client` already exists.
2. `createClient` with `displayName` and `clientType` (`Frontend` or `Backend`).
3. `getContextSchema` to confirm that a `country` field exists. If not, `addContextField` adds it.
4. `createFlag` with `flagName`, `clientName`, `schemaObject`, and `variants`.
5. `addTargetingRule` with `variantAllocations` that sum to 100 and a `payload` with the country condition.

**Check the result:** Ask the assistant to run `getFlag` with `summary=false` and confirm that the rule and its split appear. Then follow the next recipe to resolve the flag for a test user.

## Force a Variant for a Test User

**Goal:** Make one user always get a specific variant, and confirm that they do.

**Server:** [Flags](/docs/reference/agent/mcp-flags)

**Prompt:**

```text theme={null}
Force the "on" variant of new-checkout-flow for user test-user-123 on
web-client. Then resolve the flag for that user and explain the result.
```

**What the assistant does:**

1. `getContextSchema` to find the entity field to use, such as `user_id`.
2. `addOverrideRule` with `flagName`, `entity`, `entityValue`, and `variantName`.
3. `resolveFlag` with `flagName`, `clientName`, `entity`, and `entityValue`.

**Check the result:** The `resolveFlag` output explains each evaluation step. Confirm that the override rule matched and that the variant is `on`. To turn the override off later, ask the assistant to call `updateOverrideRule` with `enabled` set to `false`, or `deleteRule` to remove it.

## Roll a Flag Out to a Percentage

**Goal:** Turn a feature on for a share of matching users, and increase that share later.

**Server:** [Flags](/docs/reference/agent/mcp-flags)

**Prompt:**

```text theme={null}
Roll out the "on" variant of new-checkout-flow to 25% of users on
web-client. Everyone outside the 25% should fall through to the default.
```

**What the assistant does:**

1. `getFlag` to read the flag's variants and existing rules.
2. `addTargetingRule` with `variantAllocations` set to `{"on": 100}` and `rolloutPercentage` set to `25`. Users outside the 25% fall through to the next rule.
3. To change the percentage later, `deleteRule` removes the rule and `addTargetingRule` adds it again with the new `rolloutPercentage`. `updateTargetingRule` changes a rule's targeting, variant split, or enabled state, but not its rollout percentage.

**Check the result:** Run `getFlag` with `summary=false` to see the rollout percentage on the rule. Resolve the flag for a few users with `resolveFlag` to see which ones enter the rule.

To measure the impact of a rollout, create it as a rollout in Confidence instead. See [Roll Out a Change](/docs/guides/roll-out-a-change).

## Define an Event and Build a Metric on It

**Goal:** Register a custom event, confirm that it arrives, and create a metric from it.

**Server:** [Flags](/docs/reference/agent/mcp-flags)

**Prompt:**

```text theme={null}
Create an event definition called checkout-completed with fields
order_value (number) and currency (string). After I send some events,
check that they arrive. Then create a metric for average order value per
user from the checkout-completed fact table.
```

**What the assistant does:**

1. `createEventDefinition` with `eventDefinitionId` and `schema`.
2. You send events from your application with the SDK `track()` method. See [Send Product Events](/docs/guides/send-product-events).
3. `queryEventsUsage` with `eventDefinitionName` and `daysBack` to show hourly publish and validation failure counts.
4. `listFactTables` to find the fact table that Confidence creates when events start arriving.
5. `listEntities` to find the entity, such as users.
6. `createMetric` with `displayName`, `entity`, `factTable`, and a `typeSpec` such as `{"averageMetricSpec":{"measurement":"order_value","aggregation":"SUM"}}`.

**Check the result:** `queryEventsUsage` shows publish counts above zero and no validation failures. `getMetric` returns the new metric. To see values, follow the next recipe.

## Calculate a Metric over a Time Window

**Goal:** Compute a metric over historical data in your warehouse.

**Server:** [Flags](/docs/reference/agent/mcp-flags)

**Prompt:**

```text theme={null}
Calculate the average order value metric for the last 14 days using the
new-checkout-flow exposure table, and show me the daily time series.
```

**What the assistant does:**

1. `checkWarehouseExists`. Metric calculations require a warehouse. If none exists, follow [Connect a Warehouse](#connect-a-warehouse).
2. `listMetrics` and `listExposureTables` to find the metric and exposure table names.
3. `createMetricCalculation` with `metric`, `exposureTable`, `startTime`, and `endTime`.
4. `getMetricCalculation` until the state is `STATE_COMPLETED`.
5. `queryMetricCalculation` with `groupByDimensions` and `accumulateDimension` set to `cohort_date` for a time series.

**Check the result:** The assistant reports count, mean, variance, and sum per dimension. If the state is `STATE_FAILED`, ask the assistant to show the calculation details from `getMetricCalculation`.

## Check an Experiment's Results

**Goal:** Find an experiment and read its results.

**Server:** [Experiments](/docs/reference/agent/mcp-experiments)

**Prompt:**

```text theme={null}
Find the running checkout A/B test and summarize its results: the effect
on each metric, the confidence intervals, and any warnings.
```

**What the assistant does:**

1. `list_experiments` with `query` set to `checkout`, or with a `filter` for state.
2. `get_experiment` with `experimentName` to read the metrics, decision, and analysis result names.
3. `get_results` with `analysisResultName` to read effect estimates, confidence intervals, and status messages.
4. `get_resource` to look up any metric or segment that the results reference.

**Check the result:** Compare the summary with the experiment's results page in Confidence. Set `summary=false` on `get_results` for the full output.

## Clean Up Unused Flags

**Goal:** Find flags on a client that nothing uses or that are at full rollout, and archive the ones you no longer need.

**Server:** [Flags](/docs/reference/agent/mcp-flags)

**Prompt:**

```text theme={null}
Analyze flag usage on web-client and list flags that are unused or fully
rolled out. For each one, show its recent history. Archive the ones I
confirm.
```

**What the assistant does:**

1. `analyzeFlagUsage` with `clientName`.
2. `getFlagHistory` with `flagName`, `fromDate`, and `toDate` for each candidate.
3. After you confirm, `archiveFlag` with `flagName` for each flag.

**Check the result:** `listFlags` with `state` set to `ARCHIVED` lists the archived flags. An archived flag no longer resolves, so remove its code paths first. To restore a flag, ask the assistant to call `unarchiveFlag`.

## Connect a Warehouse

**Goal:** Connect your data warehouse so Confidence can write assignments and events and calculate metrics.

**Server:** [Flags](/docs/reference/agent/mcp-flags)

**Prompt:**

```text theme={null}
Connect our BigQuery warehouse. Validate the configuration first, then
create the warehouse and set up connections that export flag resolve
events and custom events to it.
```

**What the assistant does:**

1. `checkWarehouseExists` to confirm that the account has no warehouse yet.
2. `validateWarehouseConfig` with `warehouseType` and `configJson` to check access to datasets, schemas, and roles.
3. `createWarehouse` with `warehouseType` and `configJson`.
4. `createFlagAppliedConnection` to export flag resolve events.
5. `createEventConnection` to export custom events.

For Snowflake key-pair authentication, the assistant first calls `createCryptoKey`. You then register the public key in Snowflake.

**Check the result:** `checkWarehouseExists` reports a warehouse. After flags resolve, `listExposureTables` lists exposure tables.

## Record a Sample of Sessions

**Goal:** Record a sample of sessions for one client.

**Server:** [Flags](/docs/reference/agent/mcp-flags)

**Prompt:**

```text theme={null}
Create a session recording policy for web-client. Add a rule that records
10% of sessions for 50% of users in production, and enable it.
```

**What the assistant does:**

1. `createRecordingPolicy` with `displayName` and `clientName`.
2. `addRecordingRule` with `recordingPolicy`, `displayName`, `stableAudiencePercentage` set to `50`, `sessionSampleRate` set to `0.1` (a probability from 0 to 1), and `environments` as a JSON array of environment resource names. Rules are drafts by default.
3. `setRecordingRuleEnabled` with `recordingRule` and `enabled` set to `true`.

**Check the result:** `getRecordingPolicy` returns the policy with its rules in evaluation order. See [Set Up Session Recordings](/docs/guides/set-up-session-recordings) for the SDK setup.

## Get SDK Integration Code

**Goal:** Get code to add Confidence flags to your application in your language.

**Server:** [Docs and SDK guides](/docs/reference/agent/mcp-docs#docs-and-sdk-guides-mcp-server)

**Prompt:**

```text theme={null}
Show me how to integrate Confidence feature flags in this Python service
with OpenFeature, and resolve new-checkout-flow.
```

**What the assistant does:**

1. `getCodeSnippetAndSdkIntegrationTips` with `sdk`, for example `python`. Supported values are `java`, `kotlin`, `javascript`, `typescript`, `python`, `swift`, `go`, and `react`.
2. For local resolve in a backend service, `getLocalResolveIntegrationGuide` with `sdk`.
3. `searchDocumentation` or `grepDocumentation` for related details.

**Check the result:** Run the code and resolve the flag. Then use `resolveFlag` on the Flags server to compare the variant with what your application receives.