Show HN: MCP-CrashTest – Multi-step stateful contract fuzzer for MCP servers A developer released MCP-CrashTest v0.2.1, an open-source stateful contract fuzzer that runs guided multi-step random walks against Model Context Protocol servers inside ephemeral OS sandboxes and outputs deduplicated minimal JSON-RPC reproducers. Testing on 2026-11-20 in both `--adapter none` zero-shot mode and `--adapter auto` found that `mcp-server-sqlite` returns `isError: false` on SQL failures such as UNIQUE constraint violations, and that `mcp-server-git` passes human CLI formatting like "* main" from `git_branch` into `git_checkout`, `git_diff`, `git_show` and `git_merge`, which then fail. The tool requires Python >= 3.10 and targets agents that chain 5–20 tool calls, where single-step unit tests miss cross-tool contract breaks and stdio deadlocks. Unit tests check single tool calls. Real agents fail on multi-step contracts. State-aware random walks with POSIX inode-preserving rollback for Model Context Protocol MCP servers. Tools like MCP Inspector and standard unit tests validate single-step static calls . In production, AI agents execute 5–20 step tool chains where outputs from discovery/list tools feed downstream mutations, entities collide, and stdio pipes hang. Inspired by reversing the state-aware random walk paradigm from ToolSpace arXiv:2611.05036 https://arxiv.org/abs/2611.05036 —instead of keeping successful trajectories for model training and discarding rollbacks— MCP-CrashTest mines a dependency graph from tools/list , runs guided multi-step random walks inside ephemeral OS sandboxes, rolls back on failure to explore neighboring branches, prunes noisy intermediate steps, and outputs deduplicated minimal JSON-RPC reproducers . 1. Masked Errors isError: false on SQL/Runtime Failures — Protocol Violation CRITICAL In mcp-server-sqlite verified on 2026-11-20 with MCP-CrashTest v0.2.1 in both --adapter none pure zero-shot mode and --adapter auto , SQL errors return isError: false , causing agents to treat error strings as valid query results context poisoning : { "method": "tools/call", "params": { "name": "write query", "arguments": { "query": "INSERT INTO users id, name, email VALUES 1, 'CollisionBob', 'bob new@example.com' ;" } }, "response": { "text": "Database error: UNIQUE constraint failed: users.id", "isError": false } } 2. CLI Output Leaks Across Tools — Cross-Tool Contract Break HIGH In mcp-server-git , git branch outputs human CLI formatting " main" . Passing that branch name directly to git checkout , git diff , git show , or git merge fails: { "tool": "git branch", "response": { "text": " main", "isError": false } }, { "tool": "git merge", "arguments": { "source branch": " main" }, "response": { "text": "Error executing tool git merge: Ref ' main' did not resolve to an object", "isError": true } } 3. Silent State Corruption & Stdio Deadlocks — Protocol Violations CRITICAL Read-after-write verification catches tools that report isError: false without persisting state, as well as hung stdio buffers or severed child-process pipes with automatic subprocess recycling . 4. Agent Contract Smells — UX & Consistency Pitfalls MEDIUM / LOW / INFO Explicitly separated from protocol bugs: undocumented glob-only search files matching, relative vs. parent-joined path contracts, no-upsert skip behavior create entities , and intra-server isError inconsistencies. Requires Python = 3.10 . Run directly without cloning once published on PyPI uvx mcp-crashtest --target sqlite --walks 15 --depth 6 Or install from source git clone https://github.com/SnowyLumiere/mcp-crashtest.git cd mcp-crashtest pip install -e ". dev " Use -- to pass the server command cleanly without option collisions, and --adapter none to run pure zero-shot generic stateful fuzzing with zero domain-specific assumptions: mcp-crashtest \ --target my-server \ --adapter none \ --sandbox directory \ --seed 42 \ --walks 20 \ --depth 6 \ --fail-on-crash \ --output reports/my server report.md \ -- python3 -m my mcp server --root {sandbox} For stateless/API-only servers, use --sandbox none context-memory rollback and branch exploration still run : mcp-crashtest \ --target my-api-server \ --adapter none \ --sandbox none \ --walks 20 \ -- node dist/index.js --env test Requires npx filesystem / memory or uvx + git sqlite / git : mcp-crashtest --target sqlite --walks 15 --depth 6 --output reports/sqlite crash report.md mcp-crashtest --target git --walks 15 --depth 6 --output reports/git crash report.md mcp-crashtest --target filesystem --walks 15 --depth 6 --output reports/filesystem crash report.md mcp-crashtest --target memory --walks 15 --depth 6 --output reports/memory crash report.md MCP-CrashTest separates the generic zero-shot stateful engine from optional domain contract adapters mcp crashtest/adapters/ : | Capability | Generic Mode --adapter none | Built-in Domain Adapters --adapter auto | |---|---|---| | Schema Graph Mining | Infers CREATE / READ / MUTATE / DELETE + DATA / STATE / RETRY edges from tools/list ; handles Pydantic v2 anyOf / oneOf / enum and properties: null | Adds domain-specific edge bindings for filesystem , sqlite , memory , git | | Context Flow & Fuzzing | Extracts IDs/keys/URIs/paths from args & JSON responses; injects boundary strings, traversal paths, extreme ints | Adds domain-specific probes e.g. PK collisions, glob-vs-substring queries, raw main branch passing | | Post-Condition Probes | Probe A RETRY TRAP , Generic Probe B Read-After-Write on id / key / uri , Probe C SCHEMA BREAK , Probe D STDIO DEADLOCK | Adds calibrated CONTRACT SMELL checks e.g. search files glob pitfall, describe table , create entities no-upsert skip | | Report Provenance | Every finding is tagged with source: generic | Every adapter finding is explicitly tagged source: adapter: