Skip to main content
Glama
MCP Fault Server

MCP Fault Server

by buxerr

MCP Mock Server for Deterministic Fault-Injection Tests

A dependency-free Node.js MCP server fixture for integration tests. It serves initialize, ping, tools/list, and schema-checked tools/call over newline-delimited stdio JSON-RPC, with ordered fault rules for timeouts, malformed responses, permission errors, and partial tool failures.

Use it to test how an MCP client handles repeatable protocol and tool failures without contacting a model provider.

Run the fixture

Requires Node.js 20 or newer:

git clone https://github.com/buxerr/mcp-fault-server.git
cd mcp-fault-server
npm install
npm test
node src/cli.js fixtures/basic.json

The sample fixture defines a schema-checked lookup tool and injects a JSON-RPC permission error on its second call. Protocol replies go to stdout; diagnostics go to stderr.

Related MCP server: gateway_lab.mcp_server

Define tools and inject failures

Configure fixed tool results with toolResults and ordered entries in faults. A fault rule targets a 1-based occurrence of a method or a method/tool pair. A tool-specific rule takes precedence over a method-wide rule at the same occurrence.

Supported modes include:

  • timeout: emit no response for the matching request

  • malformed: emit the configured raw line

  • rpc-error: return a JSON-RPC error

  • tool-error: return an MCP tool result marked isError

The input-schema validator supports string, number, integer, and boolean properties, required keys, enums, numeric bounds, string-length bounds, and additionalProperties. It is an intentional JSON Schema subset, not a complete validator.

The programmatic API exposes MCPMockServer.handleLine for a single input line and serveStdio for newline-delimited stdio. handleLine returns a response line, null for a notification or injected timeout, or the configured malformed line.

Scope and limitations

This fixture covers deterministic tools-only MCP servers. It does not implement resources, prompts, sampling, OAuth, full JSON Schema, client negotiation, or a model provider. Injected timeouts do not sleep; clients should enforce their own timeout.

License

MIT. See LICENSE.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      C
      quality
      B
      maintenance
      Enables authoring, validating, inspecting, blackbox-inventorying, tracing, and capability-querying SPEC.md documents through MCP tools over stdio JSON-RPC. Each tool wraps the same command modules the CLI uses and returns identical JSON envelopes.
      9
      Apache 2.0
    • F
      license
      B
      quality
      C
      maintenance
      Provides a stdio MCP server with strict input validation and JSON-RPC error handling for tool calls.
      2
      -
    • A
      license
      A
      quality
      C
      maintenance
      Enables MCP hosts that require a local stdio process to connect to the hosted public demo, forwarding tool discovery and calls for fictional scheduling scenarios, product information, draft-sharing preparation, and optional feedback.
      5
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables testing AI agents against a scripted mock MCP endpoint where each tool call returns a chosen response, fails, hangs or drops the connection, and where assertions verify which tools were called, how often, in what order and with what arguments.
      13 npm
      2
      MIT