> For the complete documentation index, see [llms.txt](https://docs.flowcp.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.flowcp.ai/guides/golden-scenario-replay.md).

# Golden-scenario replay

The [Tests page](/guides/test-your-mcp-server.md) confirms your tools *register* correctly. **Golden scenarios** go one step further: they record what a read-only tool's response actually *looks like*, then replay it later to catch the most common silent breakage — an upstream API quietly renaming, removing, or retyping a field. Your tool still lists fine, but the payload it returns no longer matches what AI clients expect.

A scenario stores only the **structural shape** of the response — the set of keys and the kind of each value (string, number, object, array) — never the raw data. That keeps recordings free of real customer data and stable as live values change: only a genuine format change shows up as drift.

## Recording a scenario

1. Open your app, go to **Servers**, and click **Scenarios** on the server (branch) you want to cover. The server must be **published** — scenarios run against the live runtime.
2. In **Record a scenario**, pick a **read-only** tool. Only read tools are eligible, so recording and replay never change anything upstream.
3. Give the scenario a name and provide the **input** to call the tool with, as a JSON object (for example `{"limit": 10}`).
4. Click **Record scenario**. FlowCP calls the tool once, derives the response shape, and saves it as the golden baseline.

Re-recording a scenario with the same name overwrites its baseline and clears any previous replay result.

## Replaying

* Use **Replay** on a single scenario, or **Replay all** to run every scenario on the server.
* Each replay re-invokes the tool with the recorded input, derives the new response shape, and diffs it against the golden. The result is one of:

| Status      | Meaning                                                                                  |
| ----------- | ---------------------------------------------------------------------------------------- |
| **Passed**  | The response shape matches. New fields may have appeared (backward-compatible).          |
| **Drift**   | A recorded field was **removed** or **retyped** — a likely regression.                   |
| **Error**   | The tool call itself failed (for example, the upstream returned an error).               |
| **Skipped** | The replay couldn't run (server not published, runtime unreachable, or a missing token). |

When a scenario drifts, the row lists the offending paths — for example `removed $.email` or `retyped $.id (number → string)` — so you can see exactly what changed.

## Servers that authorize each end user (`user_oauth`)

Shared-credential servers (`api_key`, `bearer`, `none`) record and replay automatically — FlowCP uses the server's configured credential.

For **`user_oauth`** servers, FlowCP never stores end-user tokens, so it can't call the tool on its own. Provide a **temporary authorization token** in the record form (and in the **Replay authorization token** field for replays). The token is used once to make the call and is **never stored** and never logged. If you don't provide one, the scenario is reported as **Skipped**.

## When to use this

* After an upstream/Bubble API change, **Replay all** to confirm none of your read tools changed shape.
* As a quick regression check before you publish a new branch.

Golden-scenario replay only issues calls against **read-only** tools, so it is always safe to run.