CrawlCheck

Specification

CrawlCheck MCP tool lockfile, v1

Versionv1
Status—
Document kindcrawlcheck-mcp-lock
Text sha25620401640a5d0afad…

The markdown source: /spec/mcp-lockfile?format=md (or send Accept: text/markdown) · every published document: /spec/extensions.json · all specifications

Change log

Recorded automatically: each time this text changes, its sha256 and the date are added. Recording started 2026-10-14 (Mountain Time); earlier history is in the text where it states one.

Worked example

  1. Request
    curl -s 'https://crawlcheck.io/api/v1/mcp/lock?url=https://crawlcheck.io/mcp' > lock.json
  2. What comes back: a signed lockfile (kind crawlcheck-mcp-lock): a sha256 per tool and one for the whole list.
  3. Verify it offline
    curl -O https://crawlcheck.io/crawlcheck-verify.mjs
    node crawlcheck-verify.mjs --online lock.json
    The verifier is one file with no dependencies; --online fetches the published keys once.

The document

A lockfile pins the tools an operator approved on an MCP server. Before every connect, the client hashes the server's current tools/list the same way and refuses the server when anything differs. The approved tool is then the tool that runs, or nothing runs.

Make one

GET https://crawlcheck.io/api/v1/mcp/lock?url=<endpoint> (CrawlCheck runs the handshake and tools/list, calls no tool) or POST {tools: [...]} with a list you already hold. The answer is the lockfile, signed (kind crawlcheck-mcp-lock). Save it beside the server's configuration.

Format

{
  "kind": "crawlcheck-mcp-lock", "v": 1,
  "server": {"url": "https://mcp.example.com/mcp", "protocol_version": "2025-06-18", "info": {"name": "example", "version": "1.4.0"}},
  "approved_at": "2026-10-07T10:45:00.000Z",
  "tools_sha256": "…",
  "count": 3,
  "tools": [{"name": "create_issue", "sha256": "…"}, {"name": "get_issue", "sha256": "…"}, {"name": "list_issues", "sha256": "…"}],
  "jcs_v1": {"alg": "jcs-v1", "tools_sha256": "sha256-…", "extras_sha256": "sha256-…", "tools": [{"name": "create_issue", "contract": "…", "extras": "…"}]},
  "descriptions": {"create_issue": "…"},
  "scan_at_approval": {"severity": "none", "kinds": {}, "findings": []},
  "sha256": "…", "signature": "…"
}

Hashing (no server, no key)

  1. For each tool take {name, description, inputSchema, annotations} (absent fields as null).
  2. Canonical JSON: object keys sorted, no whitespace, strings as JSON escapes them. SHA-256 of the UTF-8 bytes = the tool's hash.
  3. Sort the tool hashes, join with \n, SHA-256 = tools_sha256.
  4. Read every page of tools/list (follow nextCursor) and hash the whole list. Changed 2026-11-07: before that date CrawlCheck hashed the first page only, so a lockfile it issued before then for a server that pages its tool list reports changed; re-approve it once. One-page lists hash exactly as before.
  5. At most 300 tools are hashed. When a server offers more, or when its pages could not all be read, the lockfile says so: complete: false, offered (the number of tools read) and incomplete (why). jcs_v1 still covers every tool whenever every page was read. A check against such a list answers verdict incomplete and decision block. Changed 2026-11-11: before that date the list was cut at 300 tools without a mark.

A client that does this before each connect needs nothing from CrawlCheck. POST /api/v1/mcp/lock/check {lock, tools} (or {lock, url}) returns the same comparison signed (kind crawlcheck-mcp-lock-check): verdict unchanged | changed | unreachable | incomplete, decision connect | block, the tools added, removed and modified, and for a changed description the text that moved.

Rules

jcs-v1

A second digest, published beside tools_sha256, which is unchanged. It uses RFC 8785 (JCS) canonical JSON, so two implementations in any language write the same bytes for the same list, and it keeps what the model reads and the call accepts apart from display metadata.

  1. Contract of a tool: {name, description, inputSchema, outputSchema}. description is "" and inputSchema is {} when absent or not of that type; outputSchema is present only when the server sent an object under that key (absent and {} are different contracts). title, annotations, icons, _meta and every other member are not part of it.
  2. Extras of a tool: every member it carries beyond those four (title, annotations, icons, execution, _meta, vendor members), so no other member can change without moving a digest (a wrongly typed description, inputSchema or outputSchema is normalised as in step 1 and is in neither digest; see Empty and missing fields). Strings keep their text except NUL and unpaired surrogates, which become U+FFFD; nesting deeper than 12 levels becomes "…".
  3. Canonical form: RFC 8785. Numbers are written as ECMAScript writes them (1.0 is 1), object keys in UTF-16 code-unit order, no whitespace. A tool with no name, or a number that has no IEEE 754 double (1e400), makes the list not digestible: the digest is null with a reason, never a guess.
  4. Per tool: contract = hex SHA-256 of the canonical contract; extras = hex SHA-256 of the canonical extras.
  5. Whole list: sort the contracts by name in UTF-16 code-unit order (equal names by their canonical UTF-8 bytes), write them as one canonical JSON array, SHA-256, as an SRI string (sha256-<base64>) = jcs_v1.tools_sha256. jcs_v1.extras_sha256 is SHA-256 (SRI) over the canonical form of {"tools": {name: extras}} holding only the tools that carry extras, taken in code-point order of name: a tool whose canonical extras exceed 16,384 bytes is left out and listed in "oversized": {name: bytes}, and once 262,144 bytes are used the remaining names are listed in "omitted". A list in which no tool carries extras has extras_sha256 "". Changed 2026-11-07 (the same day jcs-v1 was published): extras first covered only title, annotations and icons, in a different shape.
  6. Every page of tools/list is read (nextCursor followed) before hashing. A list whose pages could not all be read is not digested.

The whole-list digest is plain SHA-256 over RFC 8785 bytes with no CrawlCheck-specific step, so it can be compared directly with any other public record that digests the same contract fields the same way.

Test vectors. The empty list []: sha256-T1PNoYwrqgwDVLtfmj7L5e0Sq02OEbqHPC8RFhICuUU=. The one-tool list

[{"name": "read_file", "title": "Read file", "description": "Read a file from disk.",
  "inputSchema": {"type": "object", "properties": {"path": {"type": "string"}}, "required": ["path"]},
  "annotations": {"readOnlyHint": true}}]

has the canonical contract {"description":"Read a file from disk.","inputSchema":{"properties":{"path":{"type":"string"}},"required":["path"],"type":"object"},"name":"read_file"}, contract 73a730ee6b28fe0524038cd5082e673a108617d258153d44daafb2aa8eeef1f6, extras b08036e71687b7855244656f049eec719c13c214eb9575731f118331e565cb3c, tools_sha256 sha256-pUO5TdOtj4yR/mh2VDcu4y6axwVix4xgwST6cFkdd3g= and extras_sha256 sha256-Kmdz0r/Y+YnXALUVpJTXG8TUbKQhoFKQ7CeEpIw+1Oc= (over {"tools":{"read_file":{"annotations":{"readOnlyHint":true},"title":"Read file"}}}).

Where it appears: every lockfile from /api/v1/mcp/lock carries jcs_v1 (alg, tools_sha256, extras_sha256, and contract and extras for every tool; before 2026-11-11 the per-tool rows stopped at 300). The JS SDK (@crawlcheck/sdk 1.14.0, jcsV1) and the Python package (crawlcheck 1.15.0, jcs_v1) compute the same digests offline and compare on them when the approved lockfile carries jcs_v1. /api/v1/mcp/lock/check adds jcs_v1.contract_unchanged and jcs_v1.extras_unchanged when the lockfile holds a jcs_v1; the verdict and decision still come from tools_sha256. Each event in /api/v1/mcp/changes carries tools_jcs_sha256_before and tools_jcs_sha256_after once both reads have one.

The shared definition

Since 13 November 2026 every lockfile also carries tool_set_digest: the same two digests as mcp-tool-set-digest/1 defines them, a text with published test vectors that more than one implementer computes. Each side is {"digest": "sha256-…"}, {"digest": null} (no tool has extras) or {"error": "TSD-…"}. jcs-v1 is the bounded form of that definition. The two give the same values on an ordinary tool list and part in four places, where jcs-v1 repairs or bounds the input and the shared definition gives no digest:

Compare on tool_set_digest when the other party computes that definition, and on jcs_v1 against a CrawlCheck lockfile approved before this date. The JS SDK (1.15.0, toolSetDigest) and the Python package (1.16.0, tool_set_digest) compute it offline and pass all 68 published vectors.

Empty and missing fields

jcs-v1 fills defaults; it never drops a contract member. These are the same contract, with the same digest:

A wrongly typed value of those three members is in neither digest, so removing it, or replacing it with another wrongly typed value, moves nothing. Every other member counts in extras exactly as sent: no annotations, "annotations": {} and "annotations": null are three different extras digests, and "title": "" differs from no title. input_schema (snake case) is not inputSchema: it is an extras member, and the contract's inputSchema is then {}.

Implementations that omit empty fields (they drop an empty description, an empty inputSchema or outputSchema, "annotations": {} and the like before hashing) write different bytes for such a tool. Their digest of a list that holds one differs from the jcs-v1 digest even when nothing changed, and they cannot tell an absent outputSchema from {}. Lists in which every tool has a non-empty description, a non-empty inputSchema and no empty outputSchema give both the same contract bytes. A mismatch between digests of the two constructions on a list with empty fields is this divergence, not a change: to detect a change, compare two digests made the same way.

Reading the two digests together: a changed tools_sha256 (contract) means the text the model reads or the arguments the call takes or returns changed, and needs a person to re-approve. A changed extras_sha256 with the contract unchanged is a metadata edit; it still matters when a hint was dropped or reversed (readOnlyHint no longer true, destructiveHint or openWorldHint now true), and a server should bump its serverInfo.version for either kind of change.