MCP Lab / open-source testing tools

Test MCP timeouts, disconnects, and malformed responses.

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 started GitHub repository

Usable early releaseMIT licensedNode.js 22.19+stdio + HTTP

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

MCP Failure Lab

The current release covers a deliberately small set of failure modes and reporting primitives.

Capability	Behavior	Status
delay	Bounded, cancellation-aware latency from 0 to 30 seconds.	available
hang	A pending request that ends only on client cancellation.	available
disconnect	Transport loss while a tool request is in flight.	available
ping	Health and post-condition verification through a separate tool path.	available
malformed_message	One request-scoped response with an invalid JSON-RPC envelope.	available
reporting	Console and stable JSON output with CI-oriented exit codes.	available
JUnit	JUnit XML reports for CI test dashboards.	available
Streamable HTTP	Local HTTP endpoint with validated routing and shutdown.	available

Project details Documentation

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.