Examples

The repository includes these scenario files:

• delay-success.json — bounded delay with outcome and duration checks
• delay-result.json — MCP result assertions
• hang-timeout.json — expected timeout from the hanging tool
• delay-observe-ping.json — post-condition verification through ping
• protocol-ping-liveness.json — successful protocol ping during a legacy client’s in-flight call; requires the local implementation and a 2025-11-25 client
• malformed-message.json — invalid JSON-RPC response followed by a successful ping
• duplicate-response.json — repeated JSON-RPC response followed by a successful ping
• github-get-me.json — read-only authenticated-user call against GitHub MCP
• gitlab-search-projects.json — read-only project search against GitLab MCP

See External MCP targets for the GitHub and GitLab target configurations. The GitHub stdio target uses envFrom to pass an existing token from the environment without storing it in JSON. See the stdio example.

Malformed response verification

npm run dev -- run examples/scenarios/malformed-message.json

The primary call should report error, the observer should report success, and assertions should pass. See Fault Tools for the scenario JSON, variants, and Inspector checks.

Duplicate response verification

npm run dev -- run examples/scenarios/duplicate-response.json

The primary call and later ping should succeed. See Fault Tools for transport behavior and Inspector checks.

Verify with MCP Inspector

For the new protocol liveness tool, use the local build and legacy protocol instructions in Fault Tools. The built-in scenario runner can also run examples/scenarios/protocol-ping-liveness.json, which explicitly selects protocolVersion: "2025-11-25".

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

Connect with stdio, list tools, select ping, and run it. Do not share temporary authentication tokens embedded in Inspector URLs.

To inspect Streamable HTTP, start Failure Lab and Inspector in separate terminals:

npx mcp-failure-lab serve --transport http
npx @modelcontextprotocol/inspector@latest

Add http://127.0.0.1:3000/mcp as a Streamable HTTP server. See Streamable HTTP for protocol-mode guidance.

Observer verification

npm run dev -- run examples/scenarios/delay-observe-ping.json

This proves the server is responsive after the primary delay through a separate tool path on the same connection.

Future AGI experiment

This example combines Future AGI simulation and evaluation with an independent Python MCP client and the published mcp-failure-lab package. It is an integration example, not an official Future AGI integration or endorsement.

flowchart TD
    Simulation[Future AGI Simulation] --> Adapter[Test Adapter]
    Adapter --> Client[Python MCP Client]
    Client -->|stdio| Server[MCP Failure Lab]
    Server --> Hang[hang tool]
    Hang --> Timeout[Client-side Timeout]
    Timeout --> Response[Agent Failure Response]
    Response --> Evaluation[Future AGI Evaluation]

Figure 1. External validation path for the hang fault.

What was validated

The initial validation used:

• mcp-failure-lab@0.3.2 from npm
• Future AGI simulation
• Python 3.12 and the Python MCP SDK
• stdio transport
• the real hang tool
• a three-second client-side timeout

The independent client started the published package through npx, initialized an MCP session, discovered the tools available in that release, invoked hang, and observed the request remain pending until the client timeout. The same interaction was then exercised from a Future AGI simulation.

Ten generated simulation calls completed. The evaluator also identified cases where the deliberately simple adapter became repetitive after the timeout. This distinction matters: Failure Lab reproduced the fault, while the external framework evaluated the agent’s response.

Run the example

The example requires Node.js, npm, Python 3.12, a Python virtual environment, and Future AGI credentials. Install the Python dependencies required by the example:

pip install agent-simulate mcp

Configure Future AGI credentials according to its SDK documentation, then run from the repository root:

python examples/integrations/futureagi/hang_test.py

Expected MCP diagnostics include:

MCP connected: mcp-failure-lab@0.3.2
MCP tools: ['ping', 'delay', 'hang', 'disconnect']
Calling real MCP 'hang' tool (timeout=3s)...
MCP RESULT: hang timed out as expected

A successful fault reproduction means the server started, MCP initialization succeeded, hang was discoverable, and the independent client reached its configured timeout. Agent behavior after that timeout is evaluated separately.

This older integration example validates only the hang fault through its own adapter. For the built-in external-target runner, use run --target as described in External MCP targets.

See examples/integrations/futureagi for the adapter, complete setup notes, and reproduction steps.