Skip to content
MCP server

MCP Failure Lab

Fault-injection MCP server for testing how MCP clients handle timeouts and bad replies

Runs locallyStatus and history
Install
Pricing
Open source
Platforms
CLI, self-hosted
Runs
Locally
Version
0.13.2
Listing updated
2 days ago

About MCP Failure Lab

MCP Failure Lab is an open-source MCP server for developer tools. It runs locally on your machine and is started by your AI client.

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.

Install

Run in a terminal

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

Add to claude_desktop_config.json

{
  "mcpServers": {
    "mcp-failure-lab": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-failure-lab"
      ]
    }
  }
}
Install in CursorOpens Cursor, which asks you to confirm. Or add it by hand:

Add to ~/.cursor/mcp.json

{
  "mcpServers": {
    "mcp-failure-lab": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-failure-lab"
      ]
    }
  }
}
Install in VS CodeOpens VS Code, which asks you to confirm. Or add it by hand:

Add to .vscode/mcp.json

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

Add to ~/.codeium/windsurf/mcp_config.json

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

Add to your client's MCP settings (most use this shape)

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

Tools this server provides (11)

Taken from the project documentation; the running server may differ.

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.

What it does

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

Pricing

Open source

Distributed on npm; no price listed

MCP Failure Lab 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 to MCP Failure Lab

  1. REA

    MCP server

    CLI and MCP server that lets coding agents reverse engineer apps and binaries

    Runs locally
    • Open source
    • 464K GitHub stars
    • Developer tools
  2. Codebase Memory

    MCP server

    Local MCP server that builds a code knowledge graph for AI coding agents

    Runs locally
    • Open source
    • 48.7K GitHub stars
    • Knowledge and memory
  3. GitHub

    MCP server

    Official MCP server connecting AI assistants to GitHub repos, issues and workflows

    Not checked yet
    • Remote
    • Open source
    • 34.5K GitHub stars
    • Developer tools
  4. MCP toolkit giving coding agents symbol-level code retrieval and editing

    Runs locally
    • Open source
    • 31.5K GitHub stars
    • Developer tools
  5. XERJ

    MCP server

    Local search engine for AI agents with cited answers over your code and docs

    Runs locally
    • Open source
    • 19.2K GitHub stars
    • Knowledge and memory
  6. Ouroboros

    MCP server

    Spec-first layer that pins requirements and verifies results of AI coding agent work

    Runs locally
    • Open source
    • 6.4K GitHub stars
    • Developer tools