Mcp Failure Lab

A chaos-engineering and resilience-testing toolkit for Model Context Protocol servers.

Documentation · Compatibility · Project page

Quick start

Run a real deterministic delay scenario without cloning the repository or installing the package globally:

npx mcp-failure-lab demo

Example output:

MCP Failure Lab — Demo
Running a real 500ms delay scenario...

Scenario: Deterministic delay demo
Outcome: success
Duration: ~500 ms
Assertions: passed

The exact duration may vary slightly between runs. No API key or external MCP server is required.

Display the available commands:

npx mcp-failure-lab --help

Start the built-in MCP server over stdio:

npx mcp-failure-lab serve

Or start a local Streamable HTTP endpoint:

npx mcp-failure-lab serve --transport http

Purpose

MCP Failure Lab helps server authors reproduce delays, hanging tools, cancellation, transport loss, and malformed responses in a deterministic way.

It provides controlled failure behavior for testing timeout handling, cancellation cleanup, transport-loss recovery, assertions, and CI outcomes.

Current scope

MCP Failure Lab runs deterministic JSON scenarios against its built-in server or a configured external HTTP or stdio MCP target from the command line.

Available now:

• ping, delay, hang, disconnect, and malformed_message tools
• MCP communication over stdio and Streamable HTTP
• Code-first and JSON scenario definitions
• Outcome and maximum-duration assertions
• MCP result assertions
• Sequential observer calls for post-condition verification
• External MCP target orchestration through a validated adapter registry
• Streamable HTTP and stdio target configurations
• Bounded adapter setup, execution, observation, cancellation, and cleanup
• Separate scenario-assertion and adapter-lifecycle diagnostics
• Console, JSON, and JUnit XML reporting
• Machine-readable command errors
• CI-friendly exit codes
• Unit, integration, and end-to-end tests

Not implemented:

• Provider-specific adapters and recovery policies
• Duplicate-response and session-loss faults

MCP Failure Lab is not a general-purpose proxy. External targets are exercised through the same scenario calls and expectations as the built-in server.

Run against another MCP server

Pass a target configuration to execute the same scenario against a Streamable HTTP or stdio MCP server:

# From a repository checkout
npm run dev -- run path/to/scenario.json --target path/to/target.json

# With the published package and your own scenario and target files
npx mcp-failure-lab run path/to/scenario.json --target path/to/target.json

See the external MCP targets guide for complete HTTP and stdio configuration, verified GitHub and GitLab workflows, browser-based MCP Inspector validation, lifecycle diagnostics, credential handling, and troubleshooting.

The repository also includes a safe, read-only GitHub MCP example using the official remote server:

export GITHUB_MCP_AUTHORIZATION="Bearer your-token"
npm run dev -- run examples/scenarios/github-get-me.json \
  --target examples/targets/github-http.json

GitLab is available through its OAuth-capable stdio bridge:

npm run dev -- run examples/scenarios/gitlab-search-projects.json \
  --target examples/targets/gitlab-stdio.json

The first connection can open a browser for GitLab authorization. See the external-target guide for GitLab prerequisites and the difference between GitLab OAuth and GitHub token authentication.

Target-client adapter contract