Open source · CLI and GitHub Action
Snapshot an MCP server’s tool catalog and fail CI when it drifts
mcp-catalog-snap saves tools/list, prompts and resource templates as canonical JSON with a sha256 fingerprint, and reports every changed byte with its JSON path.
npx mcp-catalog-snap snapshot -- <command that starts your server>npx mcp-catalog-snap check -- <command that starts your server>For teams that ship or depend on an MCP server and want catalog changes reviewed like code.
Apache-2.0 · TypeScript · Node.js 20 or later · Built and maintained by IsoKron
What it does
- Canonical snapshots. Tools, prompts and resource templates are written as RFC 8785 canonical JSON with a sha256 fingerprint, to commit under
.mcp-catalog/. - Drift you can read.
checkre-captures the server and reports each change with its JSON path. It exits 1 on drift, 2 when it could not check, and 3 when a snapshot fails its integrity check. - Safety first. Added tools are classified read-only, write or destructive from their annotations. Tools that can write, and tools whose annotations moved toward writing, are listed first.
- A flag matrix.
matrixcaptures the server once per set of flags, such as read-only mode or toolsets, and shows which tools, annotations and schemas each set changes. - Stdio and Streamable HTTP. Point it at a server command or at a URL, with a bearer token read from a file or an environment variable and never printed.
- A GitHub Action and a static sweep. The action writes the diff to the job’s step summary.
sweepreports model-visible tokens and wire bytes per tool, and schema findings.
What it looks like
--core, which serves a smaller tool set. The check names the seven tools that went missing and the two schemas that changed, and exits 1.== kronicle-lite (.mcp-catalog/kronicle-lite.json)
fingerprint snapshot: ebd2f0092cb3a7a9e94dae9825384bf6110d464273bd5811e84a1e20c70ed4d6
fingerprint live: 4fa11b1848b3c8fa19d1eeeef47d91e60b81e9a8bdcf8430bbc5b095c3002c6a
tools: 13 -> 6 (+0 added, -7 removed, ~2 changed)
- anchor_status
- apply
- audit_query
- audit_record
- checkpoint_chain
- tombstone_block
- verify_chain
~ put_document
/inputSchema/properties/derived_from
- {"description":"Blocks (from recall) this text was derived from; when one changes, this note is…
+ <absent>
~ supersede_block
/inputSchema/properties/derived_from
- {"description":"Blocks (from recall) this text was derived from; when one changes, this note is…
+ <absent>
DRIFT: 9 reason(s)
tool removed: anchor_status
…
tool changed: supersede_block (/inputSchema/properties/derived_from)
1/1 server(s) driftedRun on 14 November 2026 against kronicle-lite. The snapshot path is shortened, and seven of the nine drift reasons are folded into “…”.
Used in our audits
Every IsoKron audit pins the server’s catalog with mcp-catalog-snap, so the report says exactly which tools, schemas and annotations were tested, and a later release can be compared with that snapshot.
To have your own server tested this way, see MCP server audits.
The rules our audits run under, with a checklist for your own server
Questions
Why fail CI on a reworded description?
Every model request carries the tool definitions, and the model plans from them, so a changed description can change what an agent does and invalidates any cached prompt prefix. With --ignore-descriptions, a description-only change is reported but does not fail the check.
Does it work with remote servers?
Yes, over Streamable HTTP with --url. The older HTTP+SSE transport is not supported; put such a server behind a stdio bridge.
Where this fits
An IsoKron audit tests whether your MCP server’s writes change the right data under concurrency, stale data, retries and partial failure, plus a targeted security review and the tool catalog’s token cost.
Request an audit or a build
Tell us which server and what you need. We reply to confirm the scope, the price and the dates.