Loadster

View saved version →

---
name: load-test
description: Author and verify a Loadster load test end to end. Write a script, validate and play it, build a load test scenario, and hand off for launch. Use when the user wants to load test, stress test, or performance test a site or API with Loadster, or asks for a Loadster script.
---

# Building a load test in Loadster

Loadster runs load tests from scripts. A script describes what one bot does; a scenario says how many bots run it,
from where, and for how long. Your job is to get a verified script and a ready scenario into the user's project.
Launching the full test is the user's job, on purpose, and no tool lets you do it.

## Before you write anything

1. **Confirm authorization.** The target must be a system the user owns or is authorized to test. If that isn't
   clear from context, ask. Loadster's terms require it and you shouldn't assume it.
2. **Pick the project.** Call `list_projects` and use the one the user names. If they're experimenting, suggest a
   separate project so the agent's work doesn't mix with the team's real tests.
3. **Read the documentation for the script type you're about to use.** Call `get_documentation` for the relevant
   topics before authoring. The server's `instructions` say the same thing, and it matters: the script formats have
   details you will get wrong from memory.
4. **Choose the script type.** Read [references/script-types.md](references/script-types.md) for the decision
   table and the documentation topic keys for each type. In short:
   - **Protocol Bots** (HTTP-level) for APIs, simple sites, and high bot counts at low cost.
   - **Browser Bots** (real Chrome, step-based) for websites and web apps where you want realistic client-side
     behavior without writing code.
   - **Playwright Test** scripts (code-first JavaScript) when the user already has Playwright tests or wants full
     control.
   Use `list_command_types` and `get_command_schema` for Protocol and Browser Bot commands, `get_scripting_api` for
   code blocks and Playwright, and `get_example` when you need a starting point.

## Author, validate, play

A saved script is unverified until it has been played. Follow this loop and don't skip steps:

1. **Create or update** the script with `create_script` or `update_script`. Use gentle, realistic think times
   between steps. Use `create_dataset` and `append_dataset_rows` when steps need varied data such as logins or
   search terms, then reference the dataset from the script.
2. **Validate** with `validate_script`. Fix every problem it reports before playing.
3. **Play** with `play_script`. This runs a single bot through the script once. Poll `get_play_status` until it
   finishes.
4. **Inspect the result.** Use `get_step_detail` for each failing or suspicious step (status codes, response bodies,
   captured values, logs), and `get_screenshot` for Browser Bot and Playwright plays. Fix the script and play again
   until every step passes for the right reasons, not just without errors. A 200 from a login page that didn't log in
   is still a failure. When a failure doesn't make sense, check the failure modes in
   [references/script-types.md](references/script-types.md) before guessing; several common ones (eventual
   consistency, slow-but-healthy flows, client-side timeouts) leave no error in the response at all.
5. **Stop** a stuck play with `stop_script` rather than leaving it running.

Tell the user what you changed between plays and why. Script updates create revisions, so
`list_script_revisions` and `restore_script_revision` can undo a bad edit.

## Build the scenario

1. Call `list_engines` to see which regions and any private engines are available.
2. Create the scenario with `create_scenario`: one or more bot groups, each with a script, a bot count, a ramp
   pattern, and a region. Start smaller than the user's target and suggest ramping up in later runs; the goal of a
   first test is usually to find where the system starts to degrade, not to knock it over.
3. Ask before anything destructive. Deleting scripts, datasets, or scenarios removes the team's work, so confirm
   with the user first even if the client doesn't prompt.

## Hand off

Summarize what you built: the script, what it does, what the play showed, and the scenario's bot groups. Point the
user to the scenario in their Loadster dashboard to launch it. Once the test has run, the `results` skill
covers reading the report.

If the tools made any of this harder than it should have been, `submit_feedback` sends a note to the Loadster team,
who read it to improve them. It's optional and nothing here depends on it. A note describes the tools, not the
user's prompts, their credentials, or anything from their account.

Referenced files: 1

View saved version →

---
name: results
description: Analyze a finished Loadster load test or a monitor incident. Read the report, find the bottleneck or failure, explain it in plain terms, and record notes. Use when the user asks what happened in a load test, whether a test passed, why a monitor is failing, or what an incident means.
---

# Reading Loadster results

## Load test reports

1. Find the test with `list_load_tests` (filter to the user's project) and fetch it with `get_load_test_report`.
   Read `get_documentation` on analyzing test results if you haven't already; the report has more in it than the
   headline numbers.
2. Look at the shape of the test before the averages. Response times and error rates plotted against the bot
   count tell you *where* the system started to struggle. A flat response time with a rising error rate, a response
   time that climbs with load, and throughput that plateaus while bots keep increasing are three different stories.
3. Separate the categories of trouble:
   - **Errors** (non-2xx, timeouts, failed validations): which steps, at what load, and did they cluster on one
     endpoint?
   - **Slowness**: which steps dominate, and does it get worse with load or is it just slow?
   - **Script problems**: failures that happen at every load level, including a single bot, are usually the script
     and not the system. Say so plainly rather than reporting them as a performance finding.
4. Use `get_step_detail` on the play or test data when you need response bodies or captured values to explain a
   failure.
5. Give the user a conclusion, not a data dump: what broke or slowed down first, at roughly what load, and the most
   likely reason based on the evidence. Be honest about what the report can't tell you; Loadster measures from
   outside and doesn't see inside the application.
6. Offer to record the conclusion with `update_load_test_notes`, and do it only after the user agrees, since notes
   are visible to the whole team.

## Monitor incidents

1. `list_monitors` and `get_monitor` to understand what the monitor checks and how often.
2. `list_incidents` and `get_incident` for the failure, then `list_monitor_cycles` around the incident time and
   `get_monitor_cycle_detail` for the failing cycles. `get_monitoring_summary` gives the longer-term picture.
3. Distinguish a real outage (consistent failures from all regions) from a flaky check (one region, one step,
   intermittent) from a broken monitor (the site changed and the script's expectations didn't). Each has a
   different fix.
4. You can fix a monitor's script with `update_monitor`, and `disable_monitor` stops a noisy one. Enabling a monitor
   and managing notification policies or maintenance windows are left to humans in the dashboard.

If anything in the tools made the analysis harder than it should have been, `submit_feedback` is there for it.
Optional, and about the tools rather than the report or the user's data.

View saved version →

---
name: setup
description: Connect Claude Code to Loadster's MCP server and verify the connection. Use when Loadster tools are missing, a Loadster tool returns 401 or unauthorized, or the user asks to set up, connect, or reconnect Loadster.
---

# Setting up the Loadster MCP connection

The Loadster plugin registers one MCP server, `loadster`, at `https://api.loadster.com/mcp`. It authenticates with
OAuth, so the user has to approve the connection once in their browser. You cannot complete that approval for them,
but you can get them there and confirm the result.

## Check whether Loadster is connected

Call `list_projects`. Three outcomes:

- **It returns projects.** The connection works. Tell the user which team's projects came back, because access is
  scoped to the team they connected in.
- **The tool is missing.** The plugin's MCP server hasn't started or isn't authenticated. Follow the steps below.
- **It fails with 401 or "unauthorized".** The OAuth connection was revoked, or the user is using a token that was
  revoked or mistyped. Follow the steps below.

## Connect with OAuth

Ask the user to:

1. Run `/mcp` in Claude Code.
2. Select **loadster** from the list and choose **Authenticate**.
3. Approve the connection in the browser window that opens. If they belong to more than one Loadster team, the
   team they pick there is the one the agent will work in.
4. Come back and confirm.

Then call `list_projects` again to verify.

## Connect with an MCP token instead

Only for headless use, CI, or clients where OAuth isn't possible. Tell the user to create a token in the Loadster
dashboard under **Settings → AI Agents → MCP Tokens**, copy it immediately (it's shown once), and register the server
outside the plugin:

```bash
claude mcp add --transport http loadster https://api.loadster.com/mcp --header "Authorization: Bearer YOUR_TOKEN"
```

Never ask the user to paste a token into the conversation, and never write a token into a file that will be
committed.

## Troubleshooting

- **Stale or missing tools after a change:** ask the user to run `/mcp` and reconnect, or restart Claude Code.
- **Wrong team's projects:** the user has to disconnect and reconnect, choosing the right team during OAuth.
- **Still stuck:** point them at https://loadster.com/manual/ai-agents/ or help@loadster.com.