# Mcp Load Lab

> Load and latency harness for Model Context Protocol (MCP) servers. Drives real tools/call traffic at configurable concurrency, measures latency percentiles and throughput, and fails CI when a server misses its performance budget. Stdlib-first, zero required dependencies for stdio.

- **Type:** MCP server
- **Install:** `agentstack add mcp-shriramkv-mcp-load-lab`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [shriramkv](https://agentstack.voostack.com/s/shriramkv)
- **Installs:** 0
- **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [shriramkv](https://github.com/shriramkv)
- **Source:** https://github.com/shriramkv/mcp-load-lab

## Install

```sh
agentstack add mcp-shriramkv-mcp-load-lab
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# mcp-load-lab

A load and latency harness for **Model Context Protocol (MCP)** servers.

Most MCP tooling checks whether a server is *correct*: does it follow the spec,
is its tool surface stable, is it safe to deploy. `mcp-load-lab` answers a
different question: **how does the server behave under concurrent load?** It
drives real `tools/call` traffic at a chosen concurrency, measures latency
percentiles and throughput, and fails your CI build when a server misses its
performance budget.

It has **no required dependencies** for the stdio transport (Python standard
library only). HTTP transport adds a single optional dependency.

## Install

```bash
pip install mcp-load-lab            # stdio transport, zero deps
pip install "mcp-load-lab[http]"    # adds streamable-HTTP support (httpx)
```

Or from a clone:

```bash
pip install -e .
```

## Quick start

Every example below works against the bundled demo server in `examples/`,
so you can try the tool before pointing it at your own.

List a server's tools:

```bash
mcp-load-lab tools --stdio "python examples/echo_server.py"
```

Ad-hoc load run, no config file needed:

```bash
mcp-load-lab quick \
  --stdio "python examples/echo_server.py" \
  --tool sleep --arg ms=20 \
  --concurrency 32 --duration 5 --warmup 1
```

```
phase    conc  reqs  rps     ok%    mean  p50   p90   p95   p99   max
-------  ----  ----  ------  -----  ----  ----  ----  ----  ----  ----
warmup*  32    1485  1454.5  100.0  21.7  21.6  22.4  22.5  23.5  23.6
load     32    4512  1498.3  100.0  21.3  21.3  21.9  22.1  22.4  22.9

(latencies in ms; * = warmup, excluded from gates)
```

## Scenario files

For repeatable runs and CI, describe the whole test in a JSON or TOML file:

```jsonc
{
  "name": "echo-sleep-ramp",
  "transport": {
    "type": "stdio",
    "command": "python",
    "args": ["examples/echo_server.py"]
  },
  "calls": [
    { "tool": "sleep", "arguments": { "ms": 20 }, "weight": 3 },
    { "tool": "echo",  "arguments": { "text": "ping" }, "weight": 1 }
  ],
  "phases": [
    { "name": "warmup", "concurrency": 4,  "duration_s": 1, "warmup": true },
    { "name": "c8",     "concurrency": 8,  "duration_s": 3 },
    { "name": "c32",    "concurrency": 32, "duration_s": 3 },
    { "name": "c64",    "concurrency": 64, "duration_s": 3 }
  ],
  "timeout_s": 10,
  "gates": {
    "max_p95_ms": 120,
    "max_error_rate": 0.01,
    "min_throughput_rps": 200
  }
}
```

Run it:

```bash
mcp-load-lab run examples/scenario.json --json report.json
```

- **`calls`** are chosen per request by `weight` (weighted random). Use this to
  model a realistic mix of tools.
- **`phases`** run in order. A `warmup` phase is measured but excluded from the
  gates. Describe a concurrency ramp by listing several phases, each with a
  higher `concurrency`.
- **`gates`** are optional thresholds. If any gate fails, the aggregate of all
  non-warmup phases is reported as `FAILED` and the process exits non-zero.

## Transports

- **stdio** launches your server as a subprocess and speaks newline-delimited
  JSON-RPC over its pipes. Concurrent requests are multiplexed over the single
  connection with distinct ids, so a server that handles requests concurrently
  shows real concurrency.

  ```jsonc
  { "type": "stdio", "command": "python", "args": ["server.py"], "env": {}, "cwd": "." }
  ```

- **http** POSTs JSON-RPC to a streamable-HTTP endpoint using a pooled client
  (needs the `http` extra). Session ids returned on `initialize` are reused.

  ```jsonc
  { "type": "http", "url": "http://localhost:8000/mcp", "headers": {} }
  ```

## CI gating

`mcp-load-lab` exits `0` when all gates pass and `1` when any gate fails, so it
drops straight into a pipeline as a performance regression check:

```yaml
- name: MCP performance budget
  run: mcp-load-lab run perf/scenario.json --json perf/report.json
```

Gates can also be set or overridden on the command line:

```bash
mcp-load-lab run perf/scenario.json \
  --max-p95 150 --max-error-rate 0.01 --min-rps 300
```

## Metrics

Per phase and for the non-warmup aggregate the harness reports request count,
throughput (requests/second over wall-clock time), success rate, and latency
`min / mean / p50 / p90 / p95 / p99 / max` in milliseconds. Percentiles use
linear interpolation over the sorted per-request latencies. Failures are
broken out by kind: `tool_error` (server returned `isError`), `rpc_error`
(JSON-RPC error), `timeout`, and `exception`.

## Demo server tools

`examples/echo_server.py` is a dependency-free async MCP server exposing four
tools chosen to exercise different load shapes: `echo` (trivial), `sleep(ms)`
(I/O-bound), `fib(n)` (CPU-bound), and `flaky(rate)` (fails with a given
probability, for testing the error path and error-rate gates).

## Load model

The engine is **closed-loop**: each phase runs a fixed number of concurrent
workers, and each worker issues one call, waits for the response, and
immediately issues the next until the phase's `duration_s` or `requests` budget
is spent. This measures how a server responds at a specific concurrency level.
Open-loop (fixed target RPS) pacing is on the roadmap.

## License

Apache-2.0. See [LICENSE](LICENSE).

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [shriramkv](https://github.com/shriramkv)
- **Source:** [shriramkv/mcp-load-lab](https://github.com/shriramkv/mcp-load-lab)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** yes
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-shriramkv-mcp-load-lab
- Seller: https://agentstack.voostack.com/s/shriramkv
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.