MCP Lab / open-source testing tools

Test MCP timeouts, disconnects, and protocol response faults.

MCP Lab develops focused tools for reproducing failure conditions in Model Context Protocol systems. The first project, MCP Failure Lab, runs deterministic scenarios against its built-in server or a configured external MCP target.

Getting startedGitHub repository
—downloads · last 30 daysStar on GitHub—
Published on npmMIT licensedNode.js 22.23.4+stdio + HTTP
Listed inOfficial MCP RegistryGitHub MCP Registry

A scenario and its result

The runner makes a real MCP tool call, records the observed outcome and duration, then evaluates the declared expectations.

delay-success.jsoninput
{
  "name": "bounded delay succeeds",
  "call": {
    "tool": "delay",
    "args": { "delayMs": 250 }
  },
  "timeoutMs": 1000,
  "expect": {
    "outcome": "success",
    "maxDurationMs": 500
  }
}
consoleoutput
$ npm run dev -- run \
  examples/scenarios/delay-success.json

Scenario:   bounded delay succeeds
Outcome:    success
Duration:   ~250 ms
Assertions: passed
What you can test

Failure paths, grouped by system layer.

Full fault reference

Start with a focused failure mode, then verify what the same connection—or a new one—can do next.

Timing & cancellation

Bounded delays, requests that hang until cancellation, and deliberately late stdio responses.

delayhangresponse_after_cancellation

Protocol & response

Invalid envelopes, duplicate results, oversized payloads, and broken progress notification sequences.

malformed_messageduplicate_responseoversized_responseinvalid_progress

Transport & session

In-flight connection loss and controlled legacy HTTP session invalidation across stdio and HTTP.

disconnectsession_lossStreamable HTTP

Verify & report

Check recovery and protocol liveness, then produce stable console, JSON, or JUnit results for CI.

pingprotocol_ping_livenessJSON + JUnit
Run your first scenarioProject details

What it is

A deterministic test server, scenario runner, assertion model, and CLI for exercising known MCP failure paths.

What it is not

It is not a general-purpose proxy or protocol compliance suite. External execution is limited to configured MCP targets and declared scenarios.