mcp_schema: dual digests (model-visible strings vs structural residue)

[blitzcrieg1]

Why

r/mcp feedback (2026-08): a single whole-schema digest treats additive optional fields and legit vendor tool adds the same as a poisoned description. Without severity, quiet weeks of legit releases bury real rug pulls.

Cutting on top-level description vs inputSchema is the wrong cut: JSON Schema carries description/title per property, and those strings are still model-visible. Demoting them would miss the poison.

Proposal

Two digests, additive format bump (single fingerprint is load-bearing today):

1. High-severity: every string the model reads (tool description, every description/title in input/output schema, annotations)
2. Low-severity: structural residue (property names, types, required, enums, nesting)

Touches: SchemaRecord / store file, fingerprint_tools / digest(), heartbeat mcp_schema_digest, mcp_schema event, Splunk prev_schema compare, Sigma rule severity.

Not in scope for a drive-by

Do not demote property-level descriptions into the quiet bucket.

Source

Peer review on https://www.reddit.com/r/mcp/comments/1vvinyo/

[Santoshkumarpuppala]

Holding the line on property-level description/title is the right call, and it is the one most implementations get wrong, because those are exactly the strings that churn and so are exactly what people demote first.

Two changes I would make to how the high bucket is defined, both from having shipped the equivalent and hit them.

Define the high bucket by exclusion, not enumeration. "Every string the model reads" is an allowlist, and an allowlist fails open on whatever the spec adds next. Mine pins six named fields per tool and has precisely this defect: anything MCP introduces later ships unpinned, silently, with no signal that coverage shrank. Inverting it — high-severity is everything except an explicit structural denylist of property names, types, required, enums, nesting — makes a new field default to loud instead of invisible. A wrong default is then noisy rather than silent, which is the failure you can actually see.

_meta is the concrete instance of that. It sits on tools, whether it reaches the model is client-dependent, and it is the obvious place to move behaviour-bearing text once descriptions are watched. Mine excludes it by design, which means text moved there produces no digest change at all. If it is not in the high bucket it deserves a stated reason rather than an omission.

One soundness point that is separate from severity: an external $ref in inputSchema hashes as a pointer, so whatever it resolves to falls outside both digests. That is not a tuning question, it is a hole in the structural digest — and it argues for resolving refs before fingerprinting, or refusing to fingerprint a schema carrying unresolved ones.

For context on where those come from: I maintain a policy enforcement point for MCP tool calls whose discovery gate does content-hash pinning per tool (https://github.com/norviq-dev/norviq). The allowlist and _meta failures are written up with the rest at https://norviq.dev/blog/the-mcp-server-you-approved/

[blitzcrieg1]

Taking all three of @Santoshkumarpuppala's points, and two of them turned out to be verifiable rather than arguable. Filed separately so they do not get buried in this issue:

• mcp_schema: _meta is stripped before hashing, so text moved there bypasses the rug-pull digest entirely #142, _meta is stripped before hashing, so text moved there bypasses both digests entirely. Confirmed on master: the poisoned and clean listings hash identically.
• mcp_schema: an external $ref in inputSchema hashes as a pointer, so its target is outside both digests #143, an external $ref in inputSchema hashes as a pointer, so its target sits outside both digests.

Both are exactly the kind of thing that cannot be found from inside a project. Thank you.

The design change to this issue

The high bucket is defined by exclusion, not enumeration.

This issue currently says high-severity covers "every string the model reads", listed out. That is an allowlist, and the argument against it is decisive: an allowlist fails open on whatever the specification adds next. A new MCP field ships unpinned, silently, with no signal that coverage shrank.

Inverted, high-severity is everything except an explicit structural denylist: property names, types, required, enums, nesting. A field nobody has thought about yet then defaults to loud rather than invisible.

That is the right default for this project. A wrong default that is noisy is a bug you can see; a wrong default that is silent is one you find during an incident. It is also the same principle already applied elsewhere here: coverage attestation reports four states rather than a boolean precisely so that "we do not know" cannot be mistaken for "fine".

So the acceptance criteria change:

• High-severity digest covers everything not on the structural denylist
• The denylist is explicit, short, and each entry carries a stated reason
• A test that adds an unknown field to a tool and asserts it moves the high digest, so the failure mode is pinned rather than assumed
• _meta is in the high bucket unless mcp_schema: _meta is stripped before hashing, so text moved there bypasses the rug-pull digest entirely #142 concludes otherwise with a written reason

$ref deliberately does not belong here. Putting it in the structural bucket would make the loud half blind to it, which is why it is #143 and not an acceptance criterion of this one.

Ordering

#142 first. It is a complete bypass of the detection this whole issue is about tuning, and tuning severity while a bypass exists is the wrong order. #142 also needs a store migration, since changing what is hashed invalidates every stored baseline, and that migration should land once rather than twice.

[blitzcrieg1]

@Santoshkumarpuppala thank you, this was the most useful review this project has had, and I checked all three rather than taking them.

_meta is confirmed and it is worse than a gap. _VOLATILE = frozenset({"_meta"}) strips it before hashing, so both the whole-listing digest and the per-tool digests added in 0.6.0 are blind to it:

baseline            4b40e8ff9183c727
with poisoned _meta 4b40e8ff9183c727   <- identical

Not a weakening, a complete bypass. And it is the same shape as two bugs this project already shipped: a reasonable-looking noise-reduction decision that silently removed signal and passed its tests because the tests shared the assumption. The comment above that line still says "keys that change between calls without changing what the model is told", which was a fair first guess and is wrong for exactly the reason you give. Filed as #142, with the store migration called out, since changing what is hashed invalidates every existing baseline and would otherwise hand every user a false rug pull on upgrade day.

$ref is confirmed too, and you are right that it is a different kind of problem. A dual-digest split would have put it in the structural bucket and made the loud half blind to it. Filed separately as #143 so that cannot happen, with "refuse to fingerprint a schema carrying unresolved external refs, and say so" as the current preference, because it turns a silent hole into a visible gap.

Exclusion over enumeration is now the design, and I have rewritten this issue's acceptance criteria around it. The argument is decisive: an allowlist fails open on whatever the spec adds next, and a wrong default that is noisy is a bug you can see. That matches how the rest of this project already behaves, where coverage is four states rather than a boolean so that "unknown" cannot be read as "fine".

You named the same defect in your own implementation while reporting it here. That is the part I want to acknowledge directly, because it is what made the report easy to act on rather than something to weigh for motive.

If you want any of it

#142 and #143 are unassigned and both are yours if you want them. #142 is the one I would take: it is a bypass rather than a tuning question, and the migration is the interesting half. If you would rather not, they get done anyway and you are credited in the issues either way.

If you have colleagues who enjoy taking a detection tool apart, please send them. The standing offer here is that a case which makes a rule fire on something legitimate is worth more than a case confirming it works, and that has now been proved four times in two weeks.

[Santoshkumarpuppala]

Reproducing _meta on master and getting identical digests is the answer — I had it as a reasoned expectation from my own implementation, not a measurement on yours.

On the offer: I would rather not claim #142 or #143, because holding an issue I cannot schedule is worse for you than leaving it unassigned. Take #142 yourself in the order you set out. What I can add is the part I have already got wrong once, on the migration.

Changing what is hashed invalidates every stored baseline, so the upgrade has two failure modes and they pull in opposite directions. Alerting on every tool is the false rug pull you named. Silently re-baselining is worse, and less visible: the first listing after upgrade becomes the new trusted prior, which means a server that changes a tool during the upgrade window gets that change laundered into the baseline as though it had always been there. That is the trust-on-first-use hole, re-entered through the migration door.

What I would want instead of either: re-baseline, and record that a re-baseline happened with the reason and the old digest, so the next drift report can say "changed since a migration on this date" rather than "changed since approval". It keeps the upgrade quiet without letting the quiet mean the same thing as verified.

Worth a test that pins it — migrate a store, mutate a tool in the same window, and assert the resulting entry is distinguishable from one that was genuinely re-approved. That is the assertion I did not have.

The standing offer in your last paragraph is the right one, and rarer than it should be. A case that makes a rule fire on something legitimate is the expensive kind to find, which is exactly why most projects never hear about theirs.