MCP Hook Conformance — Claude Code MCP server: what it does
CLI test harness that audits MCP servers for Claude Code hook compatibility, verifying latency, idempotency, side effects, and determinism.
claude mcp add hook-conformance -- npx -y mcp-hook-conformanceWhat MCP Hook Conformance does
The harness audits MCP tools before they are attached to Claude Code lifecycle hooks such as Stop or PreCompact. It runs five targeted test suites covering output reproducibility, latency bounds under standard thresholds, floating-point drift, state mutations, and data retention disclosures.
Detecting mutations in read-only tools requires declaring a stateProbe in hook-conformance.config.json. Without that probe, the side-effects suite yields an INDETERMINATE verdict. The audit outputs specific finding codes, which can be examined with the explain command for remediation steps.
What it helps with
- audit MCP server tools for Claude Code lifecycle hook readiness
- detect unexpected state changes during read operations
- measure roundtrip tool execution latency for p50 and p95
- verify response stability without undocumented timestamps or UUIDs
Example prompts for the agent
- Run audit suites using config file
./hook-conformance.config.json - Scaffold a fresh config file for
my-mcp-server - Explain finding code
IDEMP-001and suggest fixes
How to install MCP Hook Conformance
Platform CLI
claude mcp add hook-conformance -- npx -y mcp-hook-conformancePlatform CLI
codex mcp add mcp-hook-conformance -- npx -y mcp-hook-conformanceConfig file
{
"mcpServers": {
"mcp-hook-conformance": {
"command": "npx",
"args": [
"-y",
"mcp-hook-conformance"
]
}
}
}Config file
{
"servers": {
"mcp-hook-conformance": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"mcp-hook-conformance"
]
}
}
}Platform CLI
gemini mcp add mcp-hook-conformance npx -y mcp-hook-conformanceStep by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about MCP Hook Conformance
How to install MCP Hook Conformance in Claude Code?
Run claude mcp add mcp-hook-conformance -- npx -y mcp-hook-conformance in your command line. Alternatively, run the test directly via npx mcp-hook-conformance check ./hook-conformance.config.json.
What does MCP Hook Conformance audit?
It checks MCP tools against idempotency, latency limits, determinism, data retention docs, and side effects when run inside Claude Code lifecycle hooks.
What is required to test for side effects?
You must specify a stateProbe in hook-conformance.config.json. If no probe is declared, the side-effect check evaluates to INDETERMINATE.
