CLI

demo

npx mcp-failure-lab demo

Runs the built-in deterministic delay scenario through the real execution path.

serve

npx mcp-failure-lab serve

Starts the MCP server over stdio and waits for a client.

Select Streamable HTTP explicitly:

npx mcp-failure-lab serve --transport http

Option	Default	Description
--transport	stdio	stdio or http
--host	127.0.0.1	HTTP bind host
--port	3000	HTTP listener port
--path	/mcp	Streamable HTTP endpoint

--host, --port, and --path require --transport http.

run

npm run dev -- run examples/scenarios/delay-success.json
npm run dev -- run examples/scenarios/malformed-message.json
npm run dev -- run examples/scenarios/duplicate-response.json
npm run dev -- run examples/scenarios/delay-success.json --report json
npm run --silent dev -- run examples/scenarios/delay-success.json --report junit > junit.xml
npm run dev -- run path/to/scenario.json --target path/to/target.json

Without --target, the command uses the built-in Failure Lab server. With --target, it resolves the configured adapter and runs against an external MCP server. See External MCP targets.

The malformed-message example expects a protocol error followed by a successful observer call. See Fault Tools for its inputs and expected output.

Option	Default	Description
--report	console	console, json, or junit
--target	none	External target configuration file

Reporting

Console is the default. Pass --report json for structured data or --report junit for JUnit XML. JUnit output is written to stdout.

Exit codes

Code	Meaning
0	All expectations passed
2	Scenario ran, but one or more assertions failed
1	Scenario could not be loaded or executed

JSON command error codes are invalid_arguments, scenario_load_failed, target_load_failed, and scenario_execution_failed. JUnit represents the same command failures as <error> results.