Repository navigation
SEP-1766: Digest-Pinned Tool Versioning and Interceptor-Based Validation in MCP #1766
Description
Digest-Pinned Tool Versioning and Interceptor-Based Validation in MCP
Preamble
Title: Digest-Pinned Tool Versioning and Interceptor-Based Validation in MCP
Status: Proposed
Created: 2025-11-05
Authors: @ev3rl0ng
Abstract
This SEP proposes a lightweight tool versioning protocol for Model Context Protocol (MCP): servers MUST publish a stable content digest (SHA256) for every exposed tool version in tool registries (e.g., in tools/list). All additional metadata (signatures, provenance, SBOM, revocation) is OPTIONAL and reserved for future phases. The digest enables deterministic client, or chained server as chaining progresses, pinning and fast detection of accidental or unauthorized updates, serving as a pragmatic foundation for supply chain integrity. Robust runtime validation and behavioral guardrails are delegated to the interceptor framework proposed in #1763.
Motivation
- Accidental or unplanned tool mutations threaten agent reliability; drift detection by digest is simple, high-impact and easy to integrate.
- Full artifact signing and provenance infrastructure carries high initial overhead; digest alone gives most value at lowest cost.
- Interceptor-based runtime validation (mutation/validation/observability) as proposed in SEP-1763: Interceptors for Model Context Protocol #1763, provides practical defense against malicious or unsafe tool behavior.
- Pinning by digest emulates proven workflows in open ecosystems (e.g., GitHub Action SHA pinning).
Specification
1. Digest Field for Tool Versions
- Each tool listed in MCP servers MUST include a SHA256 digest, e.g.:
{ "name": "search_repos", "semanticVersion": "1.4.2", "digest": "sha256:7d9f9c2e3d2e6c0a9e..." } - The digest MUST be calculated over a canonical code archive (ZIP/TAR) or binary payload. Servers SHOULD document the precise hashing recipe for their ecosystem. Clients MAY request the canonical archive for deferred reproducibility.
- Tool authors MAY optionally include a
commitorsourceRepofield to aid reproducibility. - All additional metadata (signature, provenance, SBOM, revocation) MAY be included but is NOT REQUIRED.
2. Client Pinning and Digest Validation
- MCP clients and agents MAY pin tool versions by digest in configuration or workflow manifests.
- Tool invocation MUST be preceded by a client-side digest check if pinned. Mismatches SHOULD result in warnings or block execution depending on policy.
- Digest pinning prohibits silent downgrade or unintentional update.
3. Interceptor Enforcement (see #1763)
- Interceptors (mutation, validation, observability) MAY be used to enforce digest pins at runtime:
- Block or warn on digests not previously allowlisted
- Require manual approval for new tool digests
- Audit digests in logs for forensic traceability
- Downscope tool invocation parameters on unvetted digests
- This enables human or automated review of tool changes without heavy cryptographic tooling.
4. Minimal Manifest Example
{
"name": "search_repos",
"semanticVersion": "1.4.2",
"digest": "sha256:7d9f9c2e3d2e6c0a9e...",
"commit": "b3f6d9e7c1a44d2f8e5a19c..."
}5. Security Considerations
- Digest pinning provides tamper evidence and integrity but NOT authenticity or non-repudiation.
- Reliance on interceptors covers runtime anti-abuse, input/output validation, audit logging, and environmental controls; together this approach gives practical defense for most operational risks.
- Malicious tool authors or compromised repos can still publish harmful code; SEP recommends escalation to signature/provenance if this threat becomes significant.
- Clients SHOULD maintain an explicit allow/blocklist of approved digests if security policy requires.
6. Upgrade Path
- Future phases could introduce optional manifest signature, provenance attestation, SBOM, transparency logs, and revocation lists.
- Backwards compatibility: servers publishing only digest + optional commit remain compliant.
- Clients and interceptors MAY opt into deeper validation as the ecosystem evolves.
Example Interceptor Policy
- Validator interceptor blocks tool invocation unless digest observed in a trusted history list.
- Observability interceptor logs tool execution with digest and agent id.
- Mutation interceptor applies strict argument schema for new/unfamiliar digests.
References
- SEP-1763: Interceptors for Model Context Protocol #1763: Standardized Interceptor Framework
- GitHub Actions SHA pinning workflows
- OCI image digest patterns
This proposal deliberately maximizes practicality and developer adoption, with clear forward compatibility for higher assurance tooling.
Reacted by Alex Nahas
Activity
[-]Digest-Pinned Tool Versioning and Interceptor-Based Validation in MCP[/-][+]SEP-1766: Digest-Pinned Tool Versioning and Interceptor-Based Validation in MCP[/+]minherz commentedon Dec 25, 2025
I noticed this proposal targets a similar problem space as SEP #1575—specifically regarding the prevention of breaking changes in agentic workflows that utilize MCP server tools.
Could you add a section to the document comparing the two approaches? It would be helpful to explicitly outline the trade-offs or specific advantages this implementation offers over the pattern proposed in #1575,
ev3rl0ng commentedon Dec 25, 2025
Mine is meant to be a cryptographic hash of the tool contents to provide some sort of proofing mechanism. Semantic versioning as proposed in #1575 doesn't really do that.
sep-automation-bot commentedon Mar 30, 2026
Friendly Reminder
Hi @ev3rl0ng!
This SEP proposal has been inactive for 94 days.
We wanted to check in:
If this proposal is no longer being pursued, please let us know and we can close it. Otherwise, any update on the current status would be appreciated!
This is an automated message from the SEP lifecycle bot.
Ratnaditya-J commentedon Apr 4, 2026
Digest pinning is exactly the right foundation for supply chain integrity; detecting tool mutations before invocation. The proposal correctly defers provenance attestation and audit logging to future phases. One observation on what those future phases might look like: pinning verifies the tool at load time, but there is still no standard for verifying what the tool actually did at runtime; which arguments were passed, what the output hash was, and whether the invocation was policy-authorized. A portable execution record that captures those per-invocation facts would sit naturally on top of the digest foundation. The digest becomes the static integrity check; the execution record becomes the runtime integrity check. I have been sketching what that execution record might look like in discussion #2493 Happy to cross-reference if useful as this SEP moves toward its future phases.
localden commentedon Apr 8, 2026
@ev3rl0ng wanted to check in and see if you are still working through this SEP. If so, could you please transform it into a SEP following the latest guidelines (Claude or another AI agent can help here)?
ev3rl0ng commentedon Apr 9, 2026
Thanks all, and apologies for going quiet on this. Given the lack of conversation on it versus #1763 I was thinking it was possibly DoA.
I’m still interested in pursuing this proposal, but after reading the feedback I think the current framing is too broad and mixes together a few separate concerns:
• compatibility/versioning
• integrity of the exact artifact being invoked
• runtime enforcement / policy
The main thing I want to preserve is the integrity piece. In particular, I think semantic versioning and digest pinning solve different problems:
• versioning communicates intended compatibility
• digest pinning detects whether the exact primitive/tool content has changed
Based on the feedback here, I think the better path is to narrow the proposal so it is not primarily about tool-level version negotiation, and instead focuses on standardized digest metadata for MCP primitives, with client-side pinning / mismatch handling as an optional behavior.
That would make this proposal:
• complementary to server-level versioning rather than competing with it
• useful even in ecosystems where clients are not ready for richer constraint resolution
• explicitly limited in scope (integrity/tamper detection, not full provenance or runtime attestation)
I’m planning to rework this into the current SEP format following the latest guidelines, and I’ll include:
If that narrower direction sounds reasonable, I’d appreciate feedback, and I’d also welcome suggestions on potential sponsorship once the rewrite is up.
Ratnaditya-J commentedon Apr 9, 2026
Digest pinning establishes that a tool hasn't changed between invocations. Does the proposal have a view on whether the same integrity guarantee should extend to the execution record produced by that tool? i.e., proof that the output wasn't altered after the fact?
ev3rl0ng commentedon Apr 9, 2026
@Ratnaditya-J, I think I want #1766 to stay focused on static integrity of MCP primitives via standardized digest metadata, not expand into broader runtime enforcement or attestation.
The distinction I see is:
• #1766: “is this the exact artifact I previously discovered/trusted?”
• #1763: Recent additions seem to handle more of the “what should happen at discovery/invocation time, and what policy or validation should be applied?”
Put differently:
• versioning is about compatibility
• digest pinning is about exact-artifact integrity
• interceptors/policy are about runtime governance
These should be complementary, not competing:
• digest metadata from #1766 can be used by interceptors/policy engines in #1763
• interceptors can enforce allow/deny behavior based on digest match/mismatch
• richer runtime receipts/attestation, if they emerge, should layer on top rather than be pulled into this SEP
So my plan is to rework this proposal into a narrower one centered on:
• standardized digest metadata for MCP primitives
• optional pinning / mismatch handling by clients or hosts
• clear non-goals around broader runtime policy, provenance, and execution attestation
I’d especially welcome feedback on:
Ratnaditya-J commentedon Apr 9, 2026
The boundary makes sense. Digest integrity at the primitive level and execution-level attestation are genuinely different problems. One answers "did this tool change?", the other answers "what did it do and can you prove it?' The layering you're describing is the right architecture. Happy to share work on the execution record layer if useful.
norika1207-lab commentedon Jun 1, 2026
Rul1an commentedon Jun 10, 2026
localden commentedon Jun 24, 2026
@ev3rl0ng closing this as SEPs have since moved to pull requests. If this is still a relevant project to pursue, feel free to create a new SEP PR and build support in our contributor Discord.
gautamgb commentedon Oct 22, 2026
@ev3rl0ng , I've been working on a narrowed version of this along the lines you suggested in April: a digest over the tool definition itself, computed by the client over what it actually received, re-checked on every tools/list. SHA-256 over the RFC 8785 form of the Tool object with the top-level _meta removed. Prompts and resource templates use the same digest.
Draft: https://gist.github.com/gautamgb/1e12c07f466389caf5af6715ee367873
Prototype: https://github.com/gautamgb/mcp-tool-pinning
It's being discussed in the Security IG thread on Discord ahead of a SEP PR. The Rationale section credits 1766 as the starting point. Would you like to co-author? If you'd take it in a different direction from the draft, let me know - good to course correct before it goes to a PR.
I used Claude Code for drafting and for the prototype, and I've reviewed all of it.
ev3rl0ng commentedon Oct 23, 2026
@gautamgb That would be great, actually. The amount of time that i had to work on things drastically dropped. I read over your proposal and I liked the general implementation proposed. I do agree that there's a potential third-party play re: the hash verification as a third level of trust. Would be interesting to see a code signing component that could use existing PKI strategies to help back it for high security implementations.
gautamgb commentedon Oct 23, 2026
@ev3rl0ng great, thank you. I've listed you as co-author in the draft as Thomas Rhoads (@ev3rl0ng). If you'd like a different name or affiliation there, let me know.
On signing, I agree it's worth doing for high-security deployments. I'd keep it out of this SEP's normative text, since this one changes nothing on the wire and SEP-3140 (signed manifests) was closed to go through a working group. The digest here is deterministic, so it's a natural payload to sign: a publisher signs the Definition Digest of each definition with existing PKI, and a host can require a valid signature before first approval on top of the pin. I added a short paragraph saying that under Rationale, so a signing extension can build on this one later.
Since your time is limited, a review pass on the draft is plenty. The prototype now covers prompts and resource templates too: https://github.com/gautamgb/mcp-tool-pinning
Draft: https://gist.github.com/gautamgb/1e12c07f466389caf5af6715ee367873