MCP Tool Surface Drift Sentinel

What this adds. SecurityRecipes now treats the MCP tool list as a runtime supply-chain surface. Tool descriptions, schemas, annotations, and capability flags are pinned, hashed, and review-gated before a changed tool can influence an agent run.

Rechecked August 23, 2026: MCP 2026-07-28 is still current and stateless. There is no negotiation handshake. Each request carries protocol version and capabilities. Servers MUST implement server/discover. --session-id and kill_session here are local run identifiers and host-session kill switches, not Mcp-Session-Id. Streamable HTTP revisions through 2025-11-25 could assign that header; 2026-07-28 ignores it and does not mint session IDs.

The product bet

The next enterprise MCP problem is not only connector intake. It is what happens after intake.

A connector can be approved on Monday and become materially different on Thursday because a vendor changes a tool description, adds a schema field, changes annotations, expands network reachability, or ships a new tool inside an already-approved namespace. For an agent, those changes are not just metadata. They alter prompt-layer instructions, approval UI, input affordances, output validation, and session risk.

The MCP Tool Surface Drift Sentinel gives the secure context layer a continuous control: fingerprint the approved surface, compare the live surface, then decide before the agent trusts it.

Signal
Load the approved baseline
Read server identity, version, endpoint/package hash, tools/resources/prompts, schemas, risk contracts, permissions, and owner.
Scope
Discover the live surface
Query or inspect current capabilities, schemas, descriptions, auth metadata, package/image, versions, and advertised extensions.
Decision
Compute semantic drift
Detect additions, removals, argument widening, required-field changes, side effects, permission expansion, auth changes, and ownership drift.
Action
Classify and contain
Accept compatible drift, require review, restrict changed tools, disable the connector, or kill active unsafe sessions.
Proof
Publish drift evidence
Record baseline/live hashes, diffs, severity, affected workflows, decisions, owners, and recertification work.

Decision gate

Is live drift backward-compatible, non-expansive, owned, and explicitly permitted by the trust and tool contracts?

Proceed

Accept the new baseline after review and recertification.

Hold or stop

Restrict or disable material unapproved capability, permission, auth, or ownership drift.

Evidence to retain

baseline and live surface snapshots
semantic drift classification
containment/recertification decision

Expected outputs

tool-surface drift report
updated baseline proposal
disablement record

Python companion

Run this playbook as a checked scenario

Detect MCP tool-surface drift

Command

python scripts/security_recipes_remediation_suite.py playbook start --playbook mcp-tool-surface-drift-sentinel --workspace . --finding finding.json --run-dir .security-recipes/runs/mcp-tool-surface-drift-sentinel

Python suite guide

What was added

Profile: data/assurance/mcp-tool-surface-drift-profile.json
Generator: scripts/generate_mcp_tool_surface_drift_pack.py
Runtime evaluator: scripts/evaluate_mcp_tool_surface_drift_decision.py
Evidence pack: data/evidence/mcp-tool-surface-drift-pack.json
MCP tools: recipes_mcp_tool_surface_drift_pack, paired with recipes_playbook_plan using playbook id mcp-tool-surface-drift-sentinel.

Regenerate and validate:

python3 scripts/generate_mcp_tool_surface_drift_pack.py
python3 scripts/generate_mcp_tool_surface_drift_pack.py --check

Evaluate a pinned live surface:

python3 scripts/evaluate_mcp_tool_surface_drift_decision.py \
  --namespace repo.contents \
  --tool-name repo.contents.patch_scoped_branch \
  --workflow-id vulnerable-dependency-remediation \
  --requested-access-mode write_branch \
  --use-baseline-hashes \
  --expect-decision allow_pinned_tool_surface

Evaluate capability expansion:

python3 scripts/evaluate_mcp_tool_surface_drift_decision.py \
  --namespace registries.quarantine \
  --tool-name registries.quarantine.stage_plan \
  --workflow-id artifact-cache-quarantine \
  --requested-access-mode approval_required \
  --capability-expansion \
  --added-capability-flag delete \
  --added-capability-flag production_credential \
  --expect-decision kill_session_on_tool_surface_signal

Decision model

Decision	Meaning
`allow_pinned_tool_surface`	The live description, schemas, annotations, and surface hash match the pinned baseline.
`allow_reviewed_tool_surface`	Drift exists, but it is tied to an explicit human review record.
`hold_for_tool_surface_review`	A description, schema, annotation, tool-list, source-kind, or trust signal needs review.
`deny_tool_surface_regression`	The live request drifts outside workflow, access-mode, or annotation boundaries.
`deny_unregistered_tool_surface`	The namespace/tool pair is not in the generated baseline.
`kill_session_on_tool_surface_signal`	A high-impact expansion or runtime signal appeared: secrets, private network, delete, publish, deploy, signer, token, approval bypass, or hidden instruction.

What gets pinned

Each baseline records:

tool name and namespace
connector ID and source kind
allowed workflow IDs
access mode and risk tier
description hash
input schema hash
output schema hash
annotation hash
aggregate surface hash
data classes, external systems, and capability flags
source artifacts used to build the pack

That lets a hosted MCP gateway answer a hard reviewer question: “Can you prove this production tool list is the one we reviewed?”

Industry alignment

This follows current primary guidance and emerging agentic security practice:

MCP Tools defines tool descriptions, schemas, annotations, structured output, and tool-list change notifications.
MCP Security Best Practices emphasizes confused-deputy, token-passthrough, SSRF, session, local server, and scope controls.
MCP Authorization anchors protected calls in resource binding, consent, and strict bearer-token handling.
OWASP MCP Top 10 calls out token exposure, scope creep, tool poisoning, supply-chain tampering, command execution, and intent-flow subversion.
OWASP Top 10 for Agentic Applications 2026 elevates tool misuse, identity abuse, agentic supply-chain risk, and cascading failures.
OWASP Agentic Skills Top 10 reinforces the same update-drift and behavior-package governance problem at the skill layer.
NIST AI RMF and the NIST Generative AI Profile frame this as governed, measured, and managed lifecycle risk.

Enterprise use

An MCP gateway should evaluate this pack when:

A server emits a tool-list changed notification.
A vendor-hosted MCP server upgrades.
A local STDIO server package changes.
A tool description, schema, annotation, data class, or external system changes.
A workflow starts with a cached tool baseline.
A high-impact action is about to execute.

The open pack is the readiness gate. The hosted-ready surface is hosted live tool-list monitoring, signed baselines, tenant-specific policy, approval workflows, and fleet drift alerts.

MCP Tool Surface Drift Sentinel

The product bet