Back to guides

Guide · Agents

MCP Tool Metadata Integrity After Approval

Install-time review of an MCP server is not a lasting trust decision. Tool descriptions and prompts can flip after a few benign calls—fingerprint approved metadata and block or re-approve on drift.

Install-time MCP review is not enough—fingerprint tools/list and treat description drift as a Tool Safety event. Primary control: Tool Safety

Approval-time trust ≠ runtime metadata

An MCP allowlist answers: which host may talk to this agent? It does not answer: what will that host claim tools do tomorrow? Clients refresh `tools/list` and prompt templates into the model as guidance. If those strings change after approval—especially after a short smoke test—you have an instruction channel the reviewer never saw.

Campaigns like Deadbugz ship a soft-looking formatter (`format_text` / `summarize`), stay clean for a few `tools/call`s, then return credential-seeking and concealment text on the next list/get. A two-call smoke test passes. Real use trips the gate. Advertising `tools.listChanged` makes the flip a protocol event, not a one-shot install artifact.

Fingerprint, then watch

1. At approval: hash the normalized `tools/list` (and any prompt templates you ingest). Record server identity, transport, owner, and why it exists (Supply Chain inventory).

2. At refresh: compare hashes. Drift is a security event—hard block or force re-approval with the new text shown to a human. Do not silently feed changed descriptions into the model.

3. Surface diffs: operators should see what changed (names, descriptions, schemas)—not only "server still connected."

4. Test the rug-pull: abuse suites must include install-clean / post-threshold flip cases. Suites that only snapshot install-time descriptions miss the class.

Allowlisting the server name without description integrity still fails after the flip. Tool Safety decides whether privileged host tools may run; metadata integrity decides whether refreshed prose can steer the plan.

What "done" looks like

You can show: (a) every production MCP has an owner and pinned identity, (b) approved tool-definition hashes exist, (c) `listChanged` / hash drift cannot expand capability without a human or hard deny, (d) traces link call count → list refresh → subsequent file/shell proposals. That is Supply Chain + Tool Safety + Observability—not a longer smoke test.

Next: Tool Safety

Open the related pillar specification for mandatory checks, artifacts, and pass conditions. Self-attest is optional.

Frequently asked questions

Isn't reviewing the MCP server at install enough?
No. Behavior can stay benign for the first few tool calls, then change tool descriptions and prompts. Approval-time review without runtime fingerprinting misses that class.
Does tools.listChanged mean the client is broken?
No. listChanged is valid MCP. The failure is treating refreshed metadata as trusted policy without integrity checks or re-consent.
How is this different from an MCP allowlist?
Allowlists decide which servers exist. Metadata integrity decides whether the descriptions those servers emit may change what the model believes without a new approval.