Load Testing with AI Agents: The Perfscale MCP Servers

What you'll build

By the end of this guide, an AI agent (Claude Code in the examples, but any MCP client works) will be able to:

Author test definitions — write perfscale YAML that is validated against the real JSON Schema before it ever lands on disk.
Run load tests locally and read back structured metrics instead of scraping terminal output.
Investigate your cloud workspace — machines, runs, p99s, logs, and OTEL time-series on perfscale.su/.ru — and dispatch runs to your fleet.

Perfscale ships two Model Context Protocol servers from the Perfscale/mcp repository:

Package	Scope	Auth
`@perfscale/mcp`	Local: wraps the open-source CLI	none — runs your local binary
`@perfscale/controlplane-mcp`	Cloud: your hosted workspace	API token (`psk_...`)

You can use either one alone. Together they cover the full loop: author and smoke-test locally, then dispatch and analyze at scale in the cloud.

Prerequisites

Node.js 20+
The perfscale binary on PATH for the local server (install instructions); run perfscale self-update — the get_schema tool needs a build with the schema subcommand
A perfscale cloud account on the Scale or Enterprise plan for the cloud server (the Starter plan does not include API access)

Part 1 — The local server: schema-validated authoring

The biggest problem with letting an agent write load-test config is silent drift: the YAML looks plausible, but a misspelled field or a wrong action ID only surfaces when the test runs — or worse, doesn't. @perfscale/mcp closes that loop: every write is linted immediately, and the agent sees schema violations in the same tool result. Invalid YAML never silently lands on disk.

Add the server to Claude Code:

claude mcp add perfscale -- npx -y @perfscale/mcp

Or in any MCP client's JSON config:

{
  "mcpServers": {
    "perfscale": {
      "command": "npx",
      "args": ["-y", "@perfscale/mcp"]
    }
  }
}

Now ask for a test in plain language:

Write a perfscale test that ramps to 200 VUs over 2 minutes against https://api.example.com/search, holds for 5 minutes, and fails if p95 exceeds 400ms. Then run it.

Watch the tool calls the agent makes:

get_schema — pulls the JSON Schema for test YAML, so field names and enum values come from your installed CLI version, not the model's memory.
write_test — creates the file and lints it against the schema in one step. A typo comes back as a lint error the agent fixes before moving on.
run_test — executes perfscale run and returns the exit code plus a parsed summary export: p50/p95/p99, error rate, RPS as structured data.

The full tool surface also includes lint, parse_summary, list_actions (the catalog of native std/* step actions), list_configs / read_config for exploring an existing test directory, and update_config / remove_config for maintenance. See the OSS MCP reference for the complete table.

The agent has no shell access through this server — it can only do what the tools allow, which is exactly the CLI's own surface.

Part 2 — The cloud server: your workspace as agent context

@perfscale/controlplane-mcp connects the agent to your hosted workspace.

Create an API token

In the dashboard, go to Settings → API Tokens (requires the manage_api_tokens permission — owners and admins by default). The plaintext token (psk_...) is shown once; store it in a secret manager. Limits per user follow your plan: Scale — 1 token, Enterprise — 5.

A token acts as you, with your role, in the workspace it was created in. Creation, revocation, and usage are all recorded in the audit log.

Configure the server

{
  "mcpServers": {
    "perfscale-cloud": {
      "command": "npx",
      "args": ["-y", "@perfscale/controlplane-mcp"],
      "env": {
        "PERFSCALE_API_URL": "https://perfscale.su",
        "PERFSCALE_API_TOKEN": "psk_..."
      }
    }
  }
}

Use https://perfscale.ru if your workspace lives there.

What the agent can now answer

The server exposes 18 tools — 16 read, 2 write. Some prompts that turn into real investigations:

"Why did p99 spike on the checkout test this week?" The agent calls list_runs to find the runs, get_run for the metric breakdown, get_run_logs for errors, and get_otel_timeseries to check CPU/memory on the machines during the run.

"Which machines are idle right now, and do we have capacity for a 500-VU run?" list_machines returns status, hardware, and benchmark capacity per machine; tenant_limits shows plan headroom.

"Re-run last night's soak test on the eu-west machines." run_test dispatches the test and returns task IDs plus log-stream URLs.

Guardrails

Only run_test and sync_git_repo write anything; both respect your RBAC permissions exactly as the dashboard does — run_test requires run_tests.
list_env_vars returns environment variable keys only — values are always masked. Your secrets never enter the agent's context.
Every action lands in the audit_log, which the agent itself can read — useful for "what changed in the workspace this week?"

Part 3 — The full loop

With both servers connected, a realistic session looks like this:

Author locally. "Write a spike test for the new QUERY endpoint" — get_schema → write_test → lint feedback → fixed YAML.
Smoke-test locally. run_test (local) with 10 VUs for 30 seconds: does it execute, does the endpoint respond?
Dispatch to the fleet. run_test (cloud) on real machines at real scale.
Analyze. get_run, query_metrics, get_otel_timeseries — the agent correlates latency percentiles with machine-level resource usage and writes you a summary.

The point isn't that the agent replaces a performance engineer. It's that the tedious parts — YAML syntax, metric plumbing, log spelunking — become a conversation, while schema validation and RBAC keep the agent inside the same rails you're on.

Troubleshooting

Symptom	Fix
`get_schema` errors mentioning the `schema` subcommand	`perfscale self-update` — you need a CLI build that ships it
`perfscale` binary not found	Put it on `PATH`, or set `PERFSCALE_BIN=/path/to/perfscale` in the server's `env`
Cloud server returns 401	Token revoked, or the workspace it was created in is no longer your active workspace
`run_test` (cloud) denied	Your role lacks the `run_tests` permission in this workspace

Next steps

OSS MCP server reference — full local tool table
Cloud MCP & API tokens — token lifecycle and the complete cloud tool list
Continuous load testing with GitHub Actions — the CI counterpart to agent-driven testing

← All guides Documentation →