# MCP Failure Lab

> MCP Failure Lab is an open-source MCP server for developer tools. Fault-injection MCP server for testing how MCP clients handle timeouts and bad replies. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Open source
- **Platforms:** CLI, self-hosted
- **Repository:** https://github.com/anilloutombam/mcp-failure-lab
- **MCP Registry name:** io.github.anilloutombam/mcp-failure-lab
- **Categories:** developer tools
- **Listing updated:** 2026-11-15

## About

Most MCP servers are built to work. This one is built to misbehave on purpose, so client and SDK authors can check what happens after a call fails: whether the connection stays usable, whether a malformed reply is rejected, and whether cleanup is clean. Behaviour is deterministic, so a failure can be reproduced in a test or in CI.

The README documents findings against specific SDK versions, including issues filed upstream for the Python, Rust, Ruby and Java SDKs. It states that these describe the versions tested, not every release. Versioned compatibility reports list reproduction steps and limits.

The server runs over stdio or a local Streamable HTTP endpoint at 127.0.0.1:3000, which has neither authentication nor TLS and should not be exposed to an untrusted network. It can also drive scenarios against an external MCP server over HTTP or stdio, but it checks results and deadlines there rather than injecting faults, since it is not a proxy.

## Features

- **Eleven fault tools:** Delay, hang, disconnect, malformed message, duplicate response, late response, session loss, oversized payload and invalid progress.
- **Deterministic scenarios:** Scenario files describe a run and its assertions so a failure repeats the same way.
- **Bounded oversized replies:** oversized_response returns 0 to 262,144 bytes of ASCII text for testing response limits.
- **External target runs:** Scenarios can call tools on another MCP server over HTTP or stdio and check results and deadlines.
- **Demo without setup:** npx mcp-failure-lab demo runs a 500 ms delay scenario with no API key or server.
- **CI reports:** Runs produce reports suited to repeatable tests in continuous integration.

## Good for

- Check that an MCP client recovers after a request times out
- Verify a client rejects responses with a bad jsonrpc field
- Test how a client handles a connection dropped mid-request
- Confirm a client enforces its response size limit
- Compare how several MCP SDKs treat duplicate or late responses

## Install

### Claude Code (Terminal)

```sh
claude mcp add mcp-failure-lab -- npx -y mcp-failure-lab
```

### Claude Desktop (claude_desktop_config.json)

```json
{
  "mcpServers": {
    "mcp-failure-lab": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-failure-lab"
      ]
    }
  }
}
```

### Cursor (~/.cursor/mcp.json)

```json
{
  "mcpServers": {
    "mcp-failure-lab": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-failure-lab"
      ]
    }
  }
}
```

### VS Code (.vscode/mcp.json)

```json
{
  "servers": {
    "mcp-failure-lab": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "mcp-failure-lab"
      ]
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

```json
{
  "mcpServers": {
    "mcp-failure-lab": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-failure-lab"
      ]
    }
  }
}
```

### Other clients (your client's MCP settings (most use this shape))

```json
{
  "mcpServers": {
    "mcp-failure-lab": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-failure-lab"
      ]
    }
  }
}
```

## Tools

- `ping`: Returns a deterministic health response.
- `protocol_ping_liveness`: Sends a bounded protocol ping during its in-flight call.
- `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.
- `malformed_message`: Violates one selected JSON-RPC response rule exactly once.
- `duplicate_response`: Sends the same JSON-RPC response twice for one request.
- `response_after_cancellation`: Sends one late response for a cancelled stdio request.
- `session_loss`: Invalidates the caller's legacy HTTP session.
- `oversized_response`: Returns a deterministic text payload up to 256 KiB.
- `invalid_progress`: Sends an unknown, regressing or late progress notification.

## FAQ

### How do I try it?

Run npx mcp-failure-lab demo. It needs Node.js 22.23.4 or newer and no API key.

### Can it inject faults into my own server?

No. External runs check tool results, deadlines and setup and cleanup, but Failure Lab is not a proxy and does not inject faults into another server.

### Is the HTTP mode safe to expose?

No. It defaults to 127.0.0.1:3000/mcp with no authentication or TLS and should not face an untrusted network.

### How large can the oversized response be?

sizeBytes accepts 0 through 262,144, on both stdio and HTTP.

### Is MCP Failure Lab free?

Yes. MCP Failure Lab is open source, so you can use and self-host it for free.

### How do I add MCP Failure Lab to Claude Code?

Run this command in your terminal: claude mcp add mcp-failure-lab -- npx -y mcp-failure-lab

### What are the best alternatives to MCP Failure Lab?

The closest alternatives to MCP Failure Lab are REA, Codebase Memory, GitHub, Serena MCP: the IDE for your agent and XERJ.

## Alternatives

- [REA](https://ai-powered.com/mcp/rea): REA is an open-source MCP server for developer tools.
- [Codebase Memory](https://ai-powered.com/mcp/codebase-memory): Codebase Memory is an open-source MCP server for knowledge and memory.
- [GitHub](https://ai-powered.com/mcp/github-2): GitHub is an open-source MCP server for developer tools.
- [Serena MCP: the IDE for your agent](https://ai-powered.com/mcp/serena-mcp-the-ide-for-your-agent): Serena MCP: the IDE for your agent is an open-source MCP server for developer tools.
- [XERJ](https://ai-powered.com/mcp/xerj): XERJ is an open-source MCP server for knowledge and memory.
- [Ouroboros](https://ai-powered.com/mcp/ouroboros): Ouroboros is an open-source MCP server for developer tools.
- [Claude Code Ultimate Guide](https://ai-powered.com/mcp/claude-code-ultimate-guide): Claude Code Ultimate Guide is an open-source MCP server for ai models and llm tooling.
- [Concord MCP](https://ai-powered.com/mcp/concord-mcp): Concord MCP is a freemium MCP server for developer tools.

---
Source: https://ai-powered.com/mcp/mcp-failure-lab-2
