⚡ MaxoPerf MCP Server

1<div align="center">
2 
3# ⚡ MaxoPerf MCP Server
4 
5### Drive the entire MaxoPerf platform from any AI agent — with your API key.
6 
7**A remote, hosted [Model Context Protocol](https://modelcontextprotocol.io) server that turns Claude, Cursor, Codex, VS Code Copilot, and ChatGPT into a full performance-testing operator. Create tests, launch load runs on managed cloud runners, read results, and get root-cause analysis — all in natural language, all authenticated with your own key.**
8 
9[![MCP](https://img.shields.io/badge/MCP-2025--11--25-8A5CF6)](https://modelcontextprotocol.io)
10[![Claude](https://img.shields.io/badge/Claude-Code%20%7C%20Desktop-8A5CF6)](https://claude.ai)
11[![Cursor](https://img.shields.io/badge/Cursor-add%20to%20app-000)](https://cursor.com)
12[![ChatGPT](https://img.shields.io/badge/ChatGPT-connector-10a37f)](https://chatgpt.com)
13 
14```
15https://app.maxoperf.com/mcp
16```
17 
18</div>
19 
20---
21 
22## Configuration
23 
24It's a **remote, hosted** server — nothing to install or run. Add this to your MCP client config and set `MAXOPERF_API_KEY` (create one in the console → **Settings → API keys**):
25 
26```json
27{
28  "mcpServers": {
29    "maxoperf": {
30      "type": "http",
31      "url": "https://app.maxoperf.com/mcp",
32      "headers": {
33        "Authorization": "Bearer ${MAXOPERF_API_KEY}"
34      }
35    }
36  }
37}
38```
39 
40Your key is validated on every call by the real platform (auth, tenancy, OpenFGA, audit) — the server stores nothing and adds no new trust boundary. Revoke the key, access dies instantly. Send the header `X-MaxoPerf-MCP-Mode: read-only` for a look-but-don't-touch session (write tools hidden).
41 
42## Install (pick your client)
43 
44**Claude Code** — the plugin bundles the server **and** the agent skill:
45```
46/plugin marketplace add MaxoPerf/mcp
47/plugin install maxoperf
48```
49Or add just the connector:
50```
51claude mcp add --transport http maxoperf https://app.maxoperf.com/mcp \
52  --header "Authorization: Bearer ${MAXOPERF_API_KEY}"
53```
54 
55**Cursor** · **VS Code / Copilot** · **Codex** · **ChatGPT** · **Claude Desktop** — one-click deeplinks and copy-paste config in [`packaging/`](./packaging). All use the same `mcpServers` block above.
56 
57---
58 
59## Tools
60 
6129 curated tools. Reads default to `response_format: "concise"` (pass `"detailed"` for the full payload); write tools require a non-read-only session, and `cancel_run` is hidden in read-only mode.
62 
63**Context & tenancy**
64- `whoami` — Resolve the account + default workspace behind your API key
65- `list_workspaces` — List workspaces visible to the account
66- `set_active_workspace` — Set the active workspace for the session
67- `list_projects` — List projects (with edit/delete permissions)
68- `create_project` — Create a project
69 
70**Tests**
71- `list_tests` — List tests (filter by project / workspace / type)
72- `get_test` — Get one test + its validation summary
73- `create_test` — Create a test shell (choose the engine/executor)
74- `get_test_overview` — Run-history overview for a test
75 
76**Test files**
77- `upload_test_file` — Upload a script/data file in one call (real 3-step presigned flow)
78- `list_test_files` — List a test's files + upload state
79- `download_test_file` — Get a short-lived download URL for a file
80 
81**Runs**
82- `start_run` — Launch a load/browser run on managed cloud runners (idempotent)
83- `get_run_status` — Poll lifecycle status (queued → running → passed/failed/cancelled)
84- `list_runs` — Paginated run history with filters
85- `cancel_run` — Cancel a run (destructive; hidden in read-only)
86- `rerun_run` — Re-run from a snapshot or the current test
87- `add_runners` — Scale a live run up at existing locations
88 
89**Results**
90- `get_run_results` — KPI overview: throughput, latency percentiles, error rate
91- `query_run_metrics` — Time-series metrics (latency / throughput / errors / load / health)
92- `get_run_errors` — Grouped error rows (message / count / code)
93 
94**Diagnostics — root-cause & anomaly detection**
95- `get_run_summary` — Executive summary + which failure criteria tripped
96- `get_run_error_bodies` — Sampled error request/response bodies + status codes
97- `get_run_logs` — Error-level engine/system log lines
98- `get_runner_health` — Runner CPU/mem trend + targetVus vs peakAchievedVus (vuShortfallPct)
99- `detect_run_anomalies` — Deterministic robust-outlier scan (median/MAD); terminal-gated, low false-positive
100 
101**Escape hatch & discovery**
102- `call_platform_api` — Reach any public `/v1/*` endpoint (secrets, environments, schedules, BYOC); admin/internal deny-listed, SSRF-safe
103- `get_openapi` — The public OpenAPI document
104- `search_endpoints` — Keyword search over the API to find the right endpoint
105 
106## Prompts
107 
108Text recipes that encode the correct tool sequence — great for chat-only clients that can't read a repo:
109 
110- `run-baseline-load-test` — Start a baseline run and watch it to completion
111- `diagnose-latency-regression` — Compare p95 across two runs
112- `summarize-run` — Plain-language summary of one run
113- `plan-and-build-test` — Turn a goal into project → test → upload → run
114- `choose-executor` — Recommend an engine (k6 / JMeter / Playwright / Selenium)
115- `scan-endpoints-for-hotspots` — Rank likely hotspots from an OpenAPI spec or pasted list
116- `setup-secrets-and-envs` — Wire workspace secrets + multi-env before a run
117- `diagnose-run-failure` — Ranked root cause for a failed run
118- `explain-run-anomalies` — Explain each detected outlier
119 
120## Resources
121 
122- `maxoperf://openapi` — The public OpenAPI spec
123- `maxoperf://run/{id}` — A run report summary
124 
125---
126 
127## Try it
128 
129- "Load test https://api.example.com/checkout with 500 users for 5 minutes and fail it if p95 goes over 800ms."
130- "Scan my repo for the endpoints most worth load-testing, then build and run a test for the riskiest one."
131- "Why did run run-0000000001 fail? Check the errors, the logs, and whether the runners actually reached the target load."
132 
133## Pair it with the brain
134 
135The MCP server is the **hands**. The bundled **[MaxoPerf agent skill](https://github.com/MaxoPerf/agent-skill)** (`npx @maxoperf/agent-skill install`, included in the Claude plugin, or in [`agent-skill/`](./agent-skill) here) is the **brain** — it reads your code, finds the hotspots, builds and runs the test, and diagnoses why it broke, driving these tools automatically.
136 
137## What's in this repo
138 
139| Path | What |
140| --- | --- |
141| [`.claude-plugin/`](./.claude-plugin) | Claude Code plugin (bundles the MCP connector + the skill) |
142| [`agent-skill/`](./agent-skill) | A copy of the `maxoperf` agent skill (canonical home: [MaxoPerf/agent-skill](https://github.com/MaxoPerf/agent-skill)) |
143| [`packaging/`](./packaging) | MCP Registry `server.json`, `.mcpb`, VS Code / Cursor deeplinks, Codex / ChatGPT setup |
144| [`LAUNCHGUIDE.md`](./LAUNCHGUIDE.md) | MCP directory listing metadata |
145 
146---
147 
148<div align="center">
149 
150**[Get started →](https://maxoperf.com)** · **[Agent skill →](https://github.com/MaxoPerf/agent-skill)** · **[Docs →](https://maxoperf.com/docs)**
151 
152<sub>Read-only mirror of the MaxoPerf monorepo. File issues at [maxoperf.com](https://maxoperf.com).</sub>
153 
154</div>
155