
MCP Failure Lab
Fault-injection MCP server for testing how MCP clients handle timeouts and bad replies
- 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-labAdd to claude_desktop_config.json
{
"mcpServers": {
"mcp-failure-lab": {
"command": "npx",
"args": [
"-y",
"mcp-failure-lab"
]
}
}
}Add to ~/.cursor/mcp.json
{
"mcpServers": {
"mcp-failure-lab": {
"command": "npx",
"args": [
"-y",
"mcp-failure-lab"
]
}
}
}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

REA
MCP serverCLI and MCP server that lets coding agents reverse engineer apps and binaries
Runs locally- Open source
- 464K GitHub stars
- Developer tools

Codebase Memory
MCP serverLocal MCP server that builds a code knowledge graph for AI coding agents
Runs locally- Open source
- 48.7K GitHub stars
- Knowledge and memory

GitHub
MCP serverOfficial MCP server connecting AI assistants to GitHub repos, issues and workflows
Not checked yet- Remote
- Open source
- 34.5K GitHub stars
- Developer tools

Serena MCP: the IDE for your agent
MCP serverMCP toolkit giving coding agents symbol-level code retrieval and editing
Runs locally- Open source
- 31.5K GitHub stars
- Developer tools

XERJ
MCP serverLocal search engine for AI agents with cited answers over your code and docs
Runs locally- Open source
- 19.2K GitHub stars
- Knowledge and memory

Ouroboros
MCP serverSpec-first layer that pins requirements and verifies results of AI coding agent work
Runs locally- Open source
- 6.4K GitHub stars
- Developer tools