Protocol-level faults
Reproduce delays, hangs, disconnects, malformed JSON-RPC messages, and duplicate responses without relying on flaky network conditions.
Open-source project
MCP Failure Lab
A TypeScript toolkit for testing how Model Context Protocol clients and servers behave under deterministic tool, transport, protocol, timeout, cancellation, and cleanup failures.
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, in CI, against its built-in server, or against another MCP target.
Published SDK test runs and their source evidence are available in MCP Observatory, where results can be compared by implementation, version, scenario, and transport.
What it tests
Two MCP transports
Exercise the built-in server over stdio or a locally safe Streamable HTTP endpoint through real MCP client and transport paths.
External MCP targets
Run the same scenario model against third-party HTTP or stdio servers through a validated adapter contract with bounded setup and cleanup.
Outcome assertions
Assert success, error, or timeout outcomes, duration limits, MCP result state, response text, and independent post-call observations.
Lifecycle diagnostics
Separate scenario failures from adapter setup, execution, cancellation, observation, and cleanup failures so reports preserve where the system broke.
Automation-ready reports
Produce console, JSON, or JUnit XML output with stable exit codes for CI, assertion failures, and execution errors.
How it works
Describe the failure. Run it through MCP. Assert what happened.
- 01
Define
Choose a built-in fault or external MCP target, its arguments, a deadline, and the expected outcome.
- 02
Exercise
The runner executes the scenario through a real MCP client over stdio or Streamable HTTP.
- 03
Verify
Assertions and optional observers evaluate timing, results, post-call health, and cleanup before producing a CI-ready report.
Use it
Run a real deterministic scenario from npm.
npx mcp-failure-lab demo