Deterministic faults
Reproduce bounded delays, hanging tools, cancellation, and transport disconnects without relying on flaky external conditions.
Open-source project
MCP Failure Lab
A TypeScript toolkit for testing how Model Context Protocol servers and clients behave when tools slow down, hang, disconnect, time out, or return an unexpected result.
The problem
The difficult paths begin when a tool stops behaving normally.
A successful tool call says little about timeout handling, cancellation cleanup, lost transports, or server health after a failure. MCP Failure Lab turns those conditions into repeatable scenarios that can run locally or in CI.
What it tests
Outcome assertions
Assert success, error, or timeout outcomes, maximum duration, MCP result state, and expected response text.
Post-call verification
Run an observer tool after the primary call to verify that the server remains responsive and its state is correct.
Automation-ready reports
Use human-readable console output or stable JSON reports, with distinct exit codes for passes, assertion failures, and execution errors.
How it works
Describe the failure. Run it through MCP. Assert what happened.
- 01
Define
Choose a fault tool, its arguments, a deadline, and the expected outcome in a JSON scenario.
- 02
Exercise
The runner starts the MCP server and executes the scenario through a real stdio client and transport.
- 03
Verify
Assertions evaluate timing and results, then an optional observer checks post-call health or state.
Use it
Run a real deterministic scenario from npm.
npx mcp-failure-lab demo