MCP Lab / MCP Failure Lab
Deterministic failure scenarios for MCP servers.
Reproduce delay, hanging requests, cancellation, and transport loss 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. 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 or JSON 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 client orchestration, Streamable HTTP, JUnit reports, malformed messages, duplicate responses, and session-loss faults are not implemented.