Skip to content
IsoKron

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.

Snapshot a stdio server
npx mcp-catalog-snap snapshot -- <command that starts your server>
Re-capture and compare, in CI
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. check re-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. matrix captures 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. sweep reports model-visible tokens and wire bytes per tool, and schema findings.

What it looks like

We snapshotted kronicle-lite, then checked it again started with --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.
mcp-catalog-snap check -- npx -y kronicle-lite serve --core
== 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) drifted

Run 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.