MCP Lab / MCP Failure Lab
Deterministic failure scenarios for MCP servers.
Reproduce delay, hanging requests, cancellation, transport loss, and malformed or duplicate JSON-RPC responses through a real MCP client/server execution path.
Quick start
No repository checkout, external MCP server, or API key is required.
terminalcommand
$ npx mcp-failure-lab demodemoresult
Scenario: Deterministic delay demo Outcome: success Duration: ~500 ms Assertions: passed
Execution model
Each scenario runs against Failure Lab’s built-in server or a configured external HTTP or stdio MCP target. The primary call and optional observer call are sequential and use the same MCP client connection.
| Stage | Responsibility | Implemented |
|---|---|---|
| Load | Validate a code-first or JSON scenario definition. | yes |
| Execute | Call a registered tool through an MCP client connection. | yes |
| Record | Capture outcome, duration, result, or execution error. | yes |
| Assert | Check outcome, maximum duration, `isError`, and returned text. | yes |
| Observe | Run a separate post-condition call such as `ping`. | yes |
| Report | Render console, JSON, or JUnit XML output and select an exit code. | yes |
CI behavior
Exit code 0 means expectations passed, 2 means assertions failed, and 1 means the scenario could not be loaded or executed.
Operational behavior
stdio protocol traffic stays on stdout. Diagnostics use stderr, and SIGINT or SIGTERM triggers graceful shutdown.
Current boundary. External HTTP and stdio MCP targets are supported. The built-in server provides malformed and duplicate JSON-RPC response faults. Late-response testing is available over stdio, and session-loss testing is available for initialized legacy HTTP sessions.