CrawlCheck MCP tool lockfile, v1
| Version | v1 |
|---|---|
| Status | — |
| Document kind | crawlcheck-mcp-lock |
| Text sha256 | 20401640a5d0afad… |
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.
2026-11-13· text sha25620401640a5d0afad…· current2026-11-11· text sha256e6f2aafff3d8c29b…2026-11-07· text sha256010619692d64d5ca…2026-11-07· text sha2563cac4a345a85a5e0…2026-10-14· text sha256f1966f19a326a31d…· first recorded
Worked example
- Request
curl -s 'https://crawlcheck.io/api/v1/mcp/lock?url=https://crawlcheck.io/mcp' > lock.json - What comes back: a signed lockfile (kind crawlcheck-mcp-lock): a sha256 per tool and one for the whole list.
- Verify it offline
The verifier is one file with no dependencies;curl -O https://crawlcheck.io/crawlcheck-verify.mjs node crawlcheck-verify.mjs --online lock.json--onlinefetches 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)
- For each tool take
{name, description, inputSchema, annotations}(absent fields asnull). - Canonical JSON: object keys sorted, no whitespace, strings as JSON escapes them. SHA-256 of the UTF-8 bytes = the tool's hash.
- Sort the tool hashes, join with
\n, SHA-256 =tools_sha256. - Read every page of
tools/list(follownextCursor) 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. - 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) andincomplete(why).jcs_v1still covers every tool whenever every page was read. A check against such a list answersverdictincompleteanddecisionblock. 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
- Any difference blocks. A new tool, a removed tool, a changed description, a changed schema, a changed annotation all count: a changed description is the usual shape of a rug pull.
- Unreachable blocks. A lockfile proves what was approved, not that the server is still that server.
- Re-approval is a person's act. The client replaces the lockfile only when someone has read the new list; the check answer's
modified_detailshows what to read. - Hashes cover what the model is handed. Server-side behaviour is outside the lockfile; a tool that keeps its description and changes what it does is a different problem (see the task canaries).
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.
- Contract of a tool:
{name, description, inputSchema, outputSchema}.descriptionis""andinputSchemais{}when absent or not of that type;outputSchemais present only when the server sent an object under that key (absent and{}are different contracts).title,annotations,icons,_metaand every other member are not part of it. - 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 typeddescription,inputSchemaoroutputSchemais 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"…". - Canonical form: RFC 8785. Numbers are written as ECMAScript writes them (
1.0is1), 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 isnullwith areason, never a guess. - Per tool:
contract= hex SHA-256 of the canonical contract;extras= hex SHA-256 of the canonical extras. - Whole list: sort the contracts by
namein 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_sha256is 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 hasextras_sha256"". Changed 2026-11-07 (the same day jcs-v1 was published): extras first covered only title, annotations and icons, in a different shape. - Every page of
tools/listis read (nextCursorfollowed) 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:
- a string or member name with an unpaired surrogate: jcs-v1 writes U+FFFD (and NUL the same way in extras); the shared definition answers
TSD-TEXTfor the digest that covers it; - a number with no IEEE 754 double: jcs-v1 digests nothing; the shared definition answers
TSD-NUMBERonly for the digest that covers it, so one in the extras leaves the contract digest standing; - two tools with one name that both carry extras: jcs-v1 keeps the one listed last; the shared definition answers
TSD-NAMEfor the extras digest; - large or deep extras: jcs-v1 leaves out a tool past 16,384 bytes and stops at 262,144 in all, naming both, and cuts nesting past 12 levels; the shared definition has no limits.
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:
- no
description,"description": "","description": null, and adescriptionthat is not a string: all are written""; - no
inputSchema,{},null, and aninputSchemathat is not an object (an array, say): all are written{}; - no
outputSchema, and anoutputSchemathat is not an object: neither is written."outputSchema": {}is written, so it is a different contract from none.
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.