MCP Failure Lab

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

MCP Failure Lab demonstrating a bounded delay and an expected timeout

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, and transport loss 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, and disconnect 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 and JSON reporting
Machine-readable command errors
CI-friendly exit codes
Unit, integration, and end-to-end tests

Not implemented:

Provider-specific adapters and recovery policies
JUnit reporting
Malformed-message, 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

The generic adapter contract drives external-target orchestration, and the deterministic test adapter verifies its lifecycle without external I/O. See the architecture documentation for lifecycle, ownership, timeout, and observation details.

How it works

MCP Failure Lab runs deterministic scenarios through its built-in MCP client and server or through a configured external HTTP or stdio target. A scenario invokes a tool, records the observed outcome and duration, and evaluates the declared expectations. Built-in scenarios use ping, delay, hang, or disconnect; external scenarios use tools exposed by their target server.

Optional observer calls run sequentially on the same MCP client connection to verify post-conditions through a separate tool path.

See the architecture documentation for diagrams, responsibilities, and implementation boundaries.

Documentation

Full guides and references are available at mcplab.dev/docs.

Requirements

Node.js 22.19.0 or newer
npm

Protocol compatibility

MCP Failure Lab targets MCP 2026-07-28 and accepts the 2025-11-25 initialization flow for compatibility. See Streamable HTTP for protocol and session details.

Installation

Run the package directly with npx:

npx mcp-failure-lab demo

No global installation is required.

To install the command globally:

npm install -g mcp-failure-lab

CLI

# Run the built-in demonstration
npx mcp-failure-lab demo

# Display command help
npx mcp-failure-lab --help

# Display the installed version
npx mcp-failure-lab --version

# Start the MCP server over stdio
npx mcp-failure-lab serve

# Start Streamable HTTP with local-safe defaults
npx mcp-failure-lab serve --transport http

# Override the HTTP endpoint explicitly
npx mcp-failure-lab serve --transport http --host localhost --port 4000 --path /mcp

The serve process waits for an MCP client. Press Ctrl+C to shut it down gracefully.

Streamable HTTP listens on http://127.0.0.1:3000/mcp by default. The server validates the request path plus Host and Origin headers. Binding another host is an explicit choice; this mode does not provide authentication or TLS, so do not expose it to an untrusted network. Put authentication and TLS termination in a trusted front end if remote access is required.

Run a scenario

Scenario files use JSON:

{
  "name": "bounded delay succeeds",
  "call": {
    "tool": "delay",
    "args": {
      "delayMs": 250
    }
  },
  "timeoutMs": 1000,
  "expect": {
    "outcome": "success",
    "maxDurationMs": 500
  }
}

From a repository checkout, run the included scenario:

npm run dev -- run examples/scenarios/delay-success.json

Generate machine-readable output:

npm run dev -- run examples/scenarios/delay-success.json --report json

The command exits with:

Code	Meaning
`0`	All expectations passed
`1`	The scenario could not be loaded or executed
`2`	One or more assertions failed

For result assertions, observer calls, reporting formats, and timeout behavior, see the scenario and reporting documentation.

Fault tools

Tool	Behavior
`ping`	Returns a deterministic health response
`delay`	Waits for a bounded duration before returning
`hang`	Remains pending until the client cancels
`disconnect`	Interrupts the active transport while a request is in flight

See the fault tools reference for arguments and behavior.

Inspect the server

Launch the official MCP Inspector web UI against the published package:

npx @modelcontextprotocol/inspector npx mcp-failure-lab serve

See External MCP targets for the complete browser-testing workflow and credential guidance.

External integration validation

See the Future AGI example for an independent Python-client validation of the hang fault. It is an external validation example, not an official integration or endorsement.

Development

Clone the repository and install its dependencies:

git clone https://github.com/anilloutombam/mcp-failure-lab.git
cd mcp-failure-lab
npm install

Run the development CLI:

npm run dev -- --help

Before opening a pull request, run:

npm run format:check
npm run typecheck
npm test
npm run build

See CONTRIBUTING.md for the contribution workflow.

Roadmap

Planned work is tracked in GitHub Issues.

Roadmap items are not part of the current implementation unless explicitly documented as available.

License

MIT

mcp failure lab