Failure Lab MCP server

MCP Failure Lab

A chaos-engineering and resilience-testing toolkit for Model Context Protocol servers.

Documentation · Compatibility · Project page

Quick start

Run a real deterministic delay scenario without cloning the repository or installing the package globally:

npx mcp-failure-lab demo

Example output:

MCP Failure Lab — Demo
Running a real 500ms delay scenario...

Scenario: Deterministic delay demo
Outcome: success
Duration: ~500 ms
Assertions: passed

The exact duration may vary slightly between runs. No API key or external MCP server is required.

Display the available commands:

npx mcp-failure-lab --help

Start the built-in MCP server over stdio:

npx mcp-failure-lab serve

Or start a local Streamable HTTP endpoint:

npx mcp-failure-lab serve --transport http

Purpose

MCP Failure Lab helps server authors reproduce delays, hanging tools, cancellation, transport loss, and malformed responses in a deterministic way.

It provides controlled failure behavior for testing timeout handling, cancellation cleanup, transport-loss recovery, assertions, and CI outcomes.

Current scope

MCP Failure Lab runs deterministic JSON scenarios against its built-in server or a configured external HTTP or stdio MCP target from the command line.

Available now:

• ping, delay, hang, disconnect, malformedmessage, and duplicateresponse tools
• MCP communication over stdio and Streamable HTTP
• Code-first and JSON scenario definitions
• Outcome and maximum-duration assertions
• MCP result assertions
• Sequential observer calls for post-condition verification
• External MCP target orchestration through a validated adapter registry
• Streamable HTTP and stdio target configurations
• Bounded adapter setup, execution, observation, cancellation, and cleanup
• Separate scenario-assertion and adapter-lifecycle diagnostics
• Console, JSON, and JUnit XML reporting
• Machine-readable command errors

Not implemented:

• Provider-specific adapters and recovery policies
• Session-loss faults

MCP Failure Lab is not a general-purpose proxy. External targets are exercised through the same scenario calls and expectations as the built-in server.

Run against another MCP server

Pass a target configuration to execute the same scenario against a Streamable HTTP or stdio MCP server:

# From a repository checkout
npm run dev -- run path/to/scenario.json --target path/to/target.json

# With the published package and your own scenario and target files
npx mcp-failure-lab run path/to/scenario.json --target path/to/target.json

Shortened. The full README is on GitHub.