SEP: Tool Risk Metadata#2793
Conversation
Extend ToolAnnotations with optional graded risk metadata (riskLevel, category, blastRadius, reversibility, sideEffects, approvalRecommendation, minTrustLevel) so MCP clients can make consistent allowlist + approval decisions across tools without each consumer rebuilding a bespoke per-tool catalogue. Pure addition; fully backward compatible. Reference impl: walbis/karai config/tool_policies.yaml. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Rename seps/9999-tool-risk-metadata.md -> seps/2793-tool-risk-metadata.md to match the allocated PR/SEP number. Updates the title heading, SEP Number cell, Issue link, and PR link in the metadata table. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Reference implementation is no longer hypothetical — heuristic classifier + CLI + 19 tests are shipping at https://github.com/walbis/mcp-risk-inferrer. - Prototype row now lists the inferrer alongside the KARAI catalogue. - Inference paragraph updates the heuristic description to match the implementation (scope-hint params for blastRadius, four risky-flag classes) and downgrades the LLM augmenter to "planned". - Reference-implementations section gives the inferrer a real bullet with status and v0.2/v0.3 roadmap. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
|
Reference implementation now exists — pushed v0.1 of the inferrer as a follow-up commit on this PR's branch and as a standalone repo:
Goal is that consumers can bootstrap risk metadata for any existing MCP server today, without waiting for every server to declare the new fields. Happy to iterate the vocabulary mapping if the spec moves during review. |
|
Strong +1 from the multi-server-host side. We run Pipeworx (a hosted MCP gateway — ~755 packs / 3,300+ tools behind one origin), and the "every platform reinvents the same vocabulary" problem is just as real on the consuming side. One concrete data point that argues for this SEP: clients already diverge on the existing binary hints. The spec makes Two field notes on the proposed fields: (1) |
|
@walbis @b-gutman the graded direction makes sense, and Bruce's required-ness point is the one I'd put front and center: a value vocabulary without a per-field optional/expected contract just pushes the divergence up a layer, the way he saw with destructiveHint. One framing that might keep this clean: treat each field as a producer-asserted hint the consumer can interpret, override, or ignore — not an authority signal. A server says reversibility: "none"; the host still decides what to gate or prompt on. If the SEP spells that out (who asserts each field, and that consumers may override), the reversibility/category vs legacy destructiveHint precedence question mostly answers itself — you're reconciling hints, not resolving authority. I'd scope approvalRecommendation as advisory-only for the same reason. |
SEP: Tool Risk Metadata
This SEP extends
ToolAnnotationswith structured, machine-readable riskmetadata so MCP clients can make consistent allowlist / approval decisions
across tools without each consumer rebuilding a bespoke per-tool catalogue.
What it adds (all optional, additive)
ToolAnnotationsalready carriesreadOnlyHint,destructiveHint,idempotentHint,openWorldHint— yes/no hints. This proposal addsgraded fields:
riskLevel: "low" | "medium" | "high" | "critical"category: "read" | "observe" | "mutate" | "delete" | "destroy" | "utility"blastRadius: "item" | "namespace" | "cluster" | "organization" | "global"reversibility: "auto" | "manual" | "none"sideEffects: string[](open vocab)approvalRecommendation: "none" | "single" | "multi"minTrustLevel: number(1–5 advisory scale)Pure addition; no breaking change. Servers and clients that don't know
these fields work exactly as today.
Motivation
Every MCP-consuming agent platform reinvents the same vocabulary. KARAI's
config/tool_policies.yaml(~30 K8s tools) is one example; Claude Desktop,Cursor, Cline, Continue, OpenDevin ship analogous configs.
destructiveHintgives a binary yes/no, but a tool deleting one row and a tool dropping a
whole namespace get the same flag.
Reference implementation
https://github.com/walbis/karai/blob/master/config/tool_policies.yaml
mcp-risk-inferrerOSS service that derives these values forservers that haven't declared them yet (verb + schema heuristic + optional
LLM augment).
File
seps/9999-tool-risk-metadata.md— happy to rename to the allocated SEPnumber on request.
Looking for sponsor + feedback on
category/blastRadius/reversibility.minTrustLevelshould be numeric or string-with-convention.follow-up SEP.