modelcontextprotocol/experimental-ext-tool-annotations
Watch
1
0
Fork
You've already forked experimental-ext-tool-annotations
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: scaffold trust/privacy extension repo from SEP-1913 carve

Browse source 
Carve the schema-bearing parts of SEP-1913 into three independent
experimental extensions, per @localden's "narrower first cut" ask and
the Tool Annotations IG's 2026-05-28 extension-first decision:

- io.modelcontextprotocol/trust-annotations (headline): narrow
  data-classification taxonomy (sensitive, untrusted) + open-ended
  evidenceRef pointer.
- io.modelcontextprotocol/action-metadata: carries forward SEP-2061
  (inputMetadata/returnMetadata/outcomes + requiresReview).
- io.modelcontextprotocol/ifc-fides: FIDES information-flow control as
  a profile of evidenceRef, not a wire root.

Adds repo meta (README, MAINTAINERS, CONTRIBUTING, LICENSE) and docs
(sep-disposition, intent-comment, decisions, open-questions,
trust-model, related-work). FIDES demoted to a profile; DataClass and
requiresReview rehomed; maliciousActivityHint and propagation parked on
the SEP-1913 umbrella. Citations index on public sources only.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This commit is contained in:
Sam Morrow 2026-06-10 23:50:22 +02:00
commit 2aea5dc6be
No known key found for this signature in database
6 changed files with 1022 additions and 1 deletions
Download patch file Download diff file Expand all files Collapse all files

91
docs/decisions.md Normal file
View file

@ -0,0 +1,91 @@
# Decision log
Append-only record of design decisions for the Tool Annotations IG's trust /
privacy extension work. Newest at the bottom.
## 2026-06-10 — Carve SEP-1913 into independent extensions
**Decision.** Split the schema-bearing parts of SEP-1913 into separate
experimental extensions, each with its own `io.modelcontextprotocol/…`
identifier and reference implementation, rather than pursuing one broad
Standards Track SEP.
**Rationale.** @localden's review asked for a *narrower first cut*; the IG
[aligned 2026-05-28](https://github.com/modelcontextprotocol/modelcontextprotocol/discussions/2820)
on an extension-first strategy. Independent extensions can graduate on their own
clock and avoid hard-to-remove schema.
## 2026-06-10 — Three initial extensions
**Decision.** `trust-annotations` (headline), `action-metadata`, `ifc-fides`.
**Rationale.** These are the three pieces with either a reference implementation
or an existing SEP behind them: Kapil's SDK, SEP-2061 (Reichel), and the FIDES
model respectively.
## 2026-06-10 — FIDES is a profile, not the headline
**Decision.** Information-flow control is `type: "ifc.fides.v1"`, a profile of
the `trust-annotations` `evidenceRef` slot — not a top-level `io.modelcontextprotocol/ifc`
extension.
**Rationale.** IFC is one enforcement model among several raised in review
(capability tokens — pshkv; cosigning — viftode4; sequence shape — marras0914).
A top-level `ifc/` root would foreclose those. Reviewer endorsement was for IFC
"if you use annotations" — i.e. as a profile.
## 2026-06-10 — `evidenceRef.type` is an open string
**Decision.** `type` MUST remain an open string with a non-binding registry of
well-known values; never a closed enum. Required fields are `digest` and
`canonicalization`; `schema` recommended; `ref` optional.
**Rationale.** Adapted from the vaaraio / Rul1an convergence in the SEP-1913
thread. An open `type` is what lets IFC, data-class, sequence-shape, and
attestation profiles share one slot.
## 2026-06-10 — `requiresReview` moves to `action-metadata`
**Decision.** `requiresReview` is an `action-metadata` field, not a
`trust-annotations` field.
**Rationale.** It is a workflow/consent signal, not a data-classification
property. Keeping it out of the trust taxonomy avoids reproducing SEP-1913's
"several concerns in one schema" problem at smaller scale.
## 2026-06-10 — DataClass demoted to a profile
**Decision.** The wire taxonomy keeps only the coarse `sensitive` boolean.
The four-level classification + regulatory scope becomes an `evidenceRef`
profile `type: "data-class.v1"`.
**Rationale.** Coarse binary is universally client-actionable and cheap on the
wire; the richer taxonomy can evolve behind a profile without a breaking schema
change.
## 2026-06-10 — Parked: maliciousActivityHint, propagation rules
**Decision.** Neither is carved into an extension now; both stay on the SEP-1913
umbrella.
**Rationale.** `maliciousActivityHint` has unresolved structural objections
(fires pre-execution at `tools/resolve`; boolean granularity wrong for UX;
clients won't trust server self-attestation). Propagation/sequence-shape needs
the taxonomy and `evidenceRef` stable first.
## 2026-06-10 — Citations: public sources only
**Decision.** Reference implementations and motivating examples cite **public**
artifacts — [`github-mcp-server`](https://github.com/github/github-mcp-server),
[`kapil8811/mcp-trust-annotations`](https://github.com/kapil8811/mcp-trust-annotations),
[arXiv:2505.23643](https://arxiv.org/abs/2505.23643) — and index on the public
SEP-1913 review record (esp. @localden). Private/internal implementations are
not named or linked.
## 2026-06-10 — Pre-flight (SEP-1862) stays core
**Decision.** These extensions are response-level and do not depend on Tool
Resolution. SEP-1862 remains a core/Standards-Track protocol change.
**Rationale.** The 2026-05-28 IG meeting concluded pre-flight is inherently a
protocol-level change, not an extension.

69
docs/intent-comment.md Normal file
View file

@ -0,0 +1,69 @@
# Intent comment (draft, pre-post review)
This is the comment we plan to post on
[SEP-1913](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/1913),
with an abbreviated pointer version for
[SEP-2061](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2061).
Kept here so it can be reviewed and stays in sync with
[sep-disposition.md](./sep-disposition.md).
---
## For SEP-1913
> **Intent: split this SEP and migrate to the Extensions Track**
>
> A note on direction for everyone following this thread. When SEP-1913 was
> first framed, the **Extensions Track** (SEP-2133) and the `experimental-ext-*`
> incubation process didn't exist in their current form. They now do, and
> they're a better fit for this work than a single Standards Track SEP.
>
> Two things pushed us here:
> - @localden's review ask for a **narrower first cut** — the concern that a
> broad taxonomy with array-or-scalar polymorphism is hard to remove or change
> once it lands.
> - The Tool Annotations IG's
> [May 28 decision](https://github.com/modelcontextprotocol/modelcontextprotocol/discussions/2820)
> to pursue trust/privacy as an **experimental extension first**, gather
> adoption evidence, then ask core maintainers to absorb anything.
>
> So the plan is to **carve this proposal into a few small,
> independently-shippable extensions**, each with its own
> `io.modelcontextprotocol/…` identifier, reference implementation, and path to
> an Extensions Track SEP. Incubation is in
> [`experimental-ext-tool-annotations`](https://github.com/modelcontextprotocol/experimental-ext-tool-annotations):
>
> | Extension | Scope |
> |---|---|
> | `trust-annotations` | The narrow data-classification taxonomy (`sensitive`, `untrusted`) + an open-ended `evidenceRef` pointer for richer, out-of-band evidence. |
> | `action-metadata` | Tool I/O + outcome contract (folds in @rreichel3's SEP-2061). |
> | `ifc-fides` | Information-flow control ([arXiv:2505.23643](https://arxiv.org/abs/2505.23643)) as **one profile** of `evidenceRef`, not a wire root — the public/private-repo confidentiality case, with github-mcp-server as emitter candidate. |
>
> Deliberately **not** in the initial carve: `maliciousActivityHint` (the
> structural concerns raised here are unresolved) and session-level propagation
> rules. Those stay parked on this umbrella thread.
>
> This follows the same Standards-Track → Extensions-Track refactor pattern as
> SEP-2127 (#2893). This PR stays open as the umbrella / problem-framing thread;
> the schema-bearing pieces move out. Feedback on the carve is very welcome —
> particularly on whether any parked item deserves its own extension sooner.
---
## For SEP-2061 (abbreviated pointer)
> Cross-linking for visibility: the Tool Annotations IG is carving the trust /
> privacy / action-metadata work into small experimental extensions in
> [`experimental-ext-tool-annotations`](https://github.com/modelcontextprotocol/experimental-ext-tool-annotations)
> (background: SEP-1913 comment
> [here](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/1913),
> and the [May 28 IG decision](https://github.com/modelcontextprotocol/modelcontextprotocol/discussions/2820)).
>
> This proposal maps directly onto the
> [`action-metadata`](https://github.com/modelcontextprotocol/experimental-ext-tool-annotations/blob/main/specification/draft/action-metadata.mdx)
> extension — `inputMetadata` / `returnMetadata` / outcomes, plus a
> `requiresReview` signal we pulled out of the trust taxonomy because it's a
> workflow concern, not a data property. The intent is to carry SEP-2061 forward
> as that extension rather than run a parallel proposal. @rreichel3 — flagging
> so we co-own it rather than diverge; happy to keep this thread as the home for
> the field semantics.

45
docs/open-questions.md Normal file
View file

@ -0,0 +1,45 @@
# Open questions
Tracked here rather than in the spec drafts, so the drafts stay non-temporal.
## Cross-cutting
- **Where does the policy-enforcement engine live** across different user
universes (cross-org, cross-domain)? Engines work well within one universe;
cross-domain is the hard case. (IG 2026-05-28.)
- **Cross-domain integrity verification** — is asymmetric crypto for domain
identity in scope for a future extension, or out of scope entirely? CLI tools
remain a persistent gap for enforcing these constraints.
- **`evidenceRef.type` registry** — who curates the list of well-known profile
types, and how do we coordinate with attestation SEPs (e.g. SEP-2787) so
values don't collide?
## trust-annotations
- Is `sensitive` the right single coarse signal, or do we need the
`data-class.v1` profile from day one?
- Content-block-level vs. result-level attachment — does the draft need a
worked multi-result example before it's implementable?
- `list_changed`: confirmed response-level annotations don't participate; revisit
only if trust vocabulary ever attaches to tool definitions.
## action-metadata
- Coexistence vs. replacement of legacy `destructiveHint` / `readOnlyHint` /
`idempotentHint` / `openWorldHint`.
- Open strings vs. closed enums for `destination` / `source` / `sensitivity`.
- Does `requiresReview` need a machine-readable *reason* for good client UX?
## ifc-fides
- Inline `_meta.ifc` for low-friction adoption vs. always behind `evidenceRef`.
- GitHub Enterprise `internal` repo visibility → public/private/reader-set
mapping (audience is the whole org, broader than collaborators).
## Parked (SEP-1913 umbrella, not carved)
- **`maliciousActivityHint`** — if it returns, it is per-`ContentBlock` with
spans, driven by the host's own detection, not a server-attested boolean.
- **Session-level propagation rules** — escalation semantics and the
sequence-shape gap ("this was call N in a flagged sequence" has no response
annotation surface today).

38
docs/related-work.md Normal file
View file

@ -0,0 +1,38 @@
# Related work
External references and prior art relevant to the IG's trust / privacy
annotation work. Several were surfaced in IG meetings (notably 2026-05-28).
## SEPs
- [SEP-1913 — Trust and Sensitivity Annotations](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/1913) — the umbrella this work carves from.
- [SEP-2061 — Action Security Metadata](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2061) — carried forward as `action-metadata`.
- [SEP-1862 — Tool Resolution / pre-flight checks](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/1862) — core-protocol, composes with these extensions.
- [SEP-2133 — Extensions](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/seps/2133-extensions.md) — the framework this repo incubates under.
- [SEP-2127 — Server Cards](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2893) — precedent for the Standards→Extensions Track refactor.
- [SEP-2787 — Tool Call Attestation](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2787) — candidate `evidenceRef` profile.
## Research
- **FIDES** — *Information-flow control for LLM agents.* [arXiv:2505.23643](https://arxiv.org/abs/2505.23643). Basis for the `ifc.fides.v1` profile.
- **Design Patterns for Securing LLM Agents** — IBM/Google/Microsoft. [arXiv:2506.08837](https://arxiv.org/abs/2506.08837). Plan-Then-Execute, Dual LLM, Map-Reduce, etc.
- **Trail of Bits** — prompt-injection via hidden content in GitHub issues. [blog](https://blog.trailofbits.com/2025/08/06/prompt-injection-engineering-for-attackers-exploiting-github-copilot/).
- **OpenAI Auto Review** — https://alignment.openai.com/auto-review/ (shared in IG chat).
## Implementations & tooling
- [`kapil8811/mcp-trust-annotations`](https://github.com/kapil8811/mcp-trust-annotations) — reference Python SDK PoC for `trust-annotations`.
- [`github-mcp-server`](https://github.com/github/github-mcp-server) — public MCP server; emitter candidate for `ifc-fides` (knows repo visibility + collaborators).
- **Ethyca** data-labeling docs — https://www.ethyca.com/docs (shared in IG chat).
- **GitHub Next** agentic-workflows research on data labeling — to be documented as issues in this repo (IG action item, @gokhanarkan / @joannakl).
## Adjacent community proposals (from the SEP-1913 thread)
- **SINT Protocol** (capability-token constraint enforcement) — pshkv.
- **in-toto** attestations as a trust-annotation substrate.
- **OVERT 1.0** envelope shape for runtime evidence.
- Caller/tool **cosigning** model — viftode4.
- **Sequence-shape** policies — marras0914.
These are exactly the models that `evidenceRef`'s open `type` is designed to
accommodate as profiles.

110
docs/sep-disposition.md Normal file
View file

@ -0,0 +1,110 @@
# SEP disposition: what happens to the existing proposals
This document explains how the existing trust/privacy/annotation SEPs map onto
the experimental extensions incubated in this repository, and what is proposed
to happen to each SEP. It exists so that anyone arriving from one of those PRs
can understand the plan without reading the whole thread.
> **Status:** proposal / options. Nothing here is decided until reflected in the
> relevant SEP PRs. The migration follows the precedent set by
> [SEP-2127 → Extensions Track (#2893)](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2893).
## Why anything changes
When [SEP-1913](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/1913)
was first framed, the **Extensions Track** ([SEP-2133](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/seps/2133-extensions.md))
and the `experimental-ext-*` incubation process did not exist in their current
form. Two inputs since then point at a different shape:
1. **Sponsor steer.** [@localden](https://github.com/localden) asked for a
*narrower first cut* — a single broad taxonomy with array-or-scalar enum
polymorphism is hard to remove or change once shipped.
2. **IG decision.** The Tool Annotations IG
[aligned on 2026-05-28](https://github.com/modelcontextprotocol/modelcontextprotocol/discussions/2820)
to pursue this work as an **experimental extension first**, build an
adoption/evidence base, and only then ask core maintainers to absorb
anything into the protocol.
The result: carve the schema-bearing parts into small, independent extensions,
each able to graduate on its own clock.
## The precedent: SEP-2127 (Server Cards)
[#2893](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2893)
refactored SEP-2127 from **Standards Track** to **Extensions Track**:
- Frontmatter `Type: Standards Track` → `Type: Extensions Track`, plus an
`Extension Identifier` and "on behalf of the WG" attribution.
- A top-of-file `<Note>` pointing at the experimental repo as the spec home.
- The SEP body **slimmed to a charter** — Abstract, Motivation, Rationale, a
high-level Specification *pointer*, security posture *summary* — with the
detailed normative wire format delegated to the extension repo.
- The SEP body kept **non-temporal**: a published SEP is frozen, so in-flight
"open items" live in the PR description and extension-repo issues, not in the
SEP text.
We apply the same playbook below.
## Per-SEP disposition
### SEP-1913 — Trust and Sensitivity Annotations
**Proposed:** becomes the **umbrella / problem-framing** thread. The schema-
bearing content is carved out into the extensions below. Options, in order of
preference:
- **(A, preferred)** Keep the PR open as the framing umbrella; add an intent
comment (see [below](#intent-comment)); later, either refactor it to an
Extensions Track *charter* that points here (SEP-2127 shape) **or** close it
in favor of per-extension Extensions Track SEPs once those are ready.
- **(B)** Refactor 1913 itself into the `trust-annotations` Extensions Track
SEP and spin the others off as siblings.
- **(C)** Close 1913 outright and open three fresh Extensions Track SEPs. Loses
the discussion history's continuity; not preferred.
**Carved out:** `trust-annotations`, `action-metadata`, `ifc-fides`.
**Parked on the umbrella (not carved):** `maliciousActivityHint`,
session-level propagation rules. See [open-questions.md](./open-questions.md).
### SEP-2061 — Action Security Metadata
**Proposed:** becomes the [`action-metadata`](../specification/draft/action-metadata.mdx)
extension. SEP-2061 is by [@rreichel3](https://github.com/rreichel3), who is
also an IG co-facilitator and SEP-1913 co-author, so this is a fold-in, not a
collision. Disposition mirrors 1913 option (A): keep the thread as the field-
semantics discussion, add a pointer comment linking it to the
`action-metadata` carve, refactor to Extensions Track when ready.
### SEP-1862 — Tool Resolution (pre-flight checks)
**Proposed:** **stays Standards Track / core.** The 2026-05-28 IG meeting
concluded pre-flight checks are inherently a protocol-level change, not an
extension. These extensions are deliberately **response-level** (`_meta` on
results, static `ToolAnnotations`) and do **not** depend on 1862. They compose
with it if it lands, but do not block on it.
### Other related SEPs (not owned here)
- **SEP-1984 (Comprehensive Tool Annotations)**, **SEP-2417 (Model Preferences
for Tools)** — tracked by the IG as discussion items; not part of this carve.
Cross-link only.
- **SEP-2787 (Tool Call Attestation)** and the various attestation/evidence
threads — these are natural `evidenceRef` *profile* candidates rather than
competitors. Coordinate so the `evidenceRef.type` registry can list them.
## Mapping table
| SEP | Title | Proposed disposition | Extension home |
| :-- | :-- | :-- | :-- |
| 1913 | Trust & Sensitivity Annotations | Umbrella thread; carve schema out | `trust-annotations` (+ `ifc-fides`) |
| 2061 | Action Security Metadata | Fold into extension | `action-metadata` |
| 1862 | Tool Resolution (pre-flight) | Stays core / Standards Track | — (composes, no dependency) |
| 1984 | Comprehensive Tool Annotations | IG discussion item | — |
| 2417 | Model Preferences for Tools | IG discussion item | — |
| 2787 | Tool Call Attestation | Candidate `evidenceRef` profile | (future) |
## Intent comment
The text we plan to post on SEP-1913 (and, abbreviated, on SEP-2061) lives in
[intent-comment.md](./intent-comment.md) so it can be reviewed before posting
and kept in sync with this document.

53
docs/trust-model.md Normal file
View file

@ -0,0 +1,53 @@
# Trust model
A single statement of the enforcement model shared by all extensions in this
repository, so individual specs don't re-litigate it.
## Annotations are claims, not guarantees
An annotation on a tool result or definition is a **claim** made by whoever
produced it. Nothing in these extensions assumes the producer is honest or
competent. The value of an annotation comes from two things:
1. **Verifiability.** Where a claim needs to be trusted, the `evidenceRef`
pointer (see [`trust-annotations`](../specification/draft/trust-annotations.mdx))
lets a consumer resolve and check the evidence behind it — re-hash the
referenced record, verify a signature, check an inclusion proof — rather
than taking the claim on faith.
2. **Accountability.** Enforcement lives with the parties that can impose
consequences: **registries and marketplaces** that admit servers,
**hosts/clients** that gate actions, and **operators** that set policy. The
annotation gives those parties a machine-readable surface to act on.
This mirrors the framing repeated throughout the SEP-1913 discussion: trust
comes from the ecosystem verifying annotations, not from developer good faith.
A server that lies in its annotations is a server a registry can refuse to list
and a host can refuse to trust — the same accountability model as any other
declared capability.
## Defense in depth, not a single gate
As framed in the IG's inaugural meeting, these annotations are **defense in
depth**: they reduce the likelihood of unintended actions (unnecessary
destructive operations, data crossing a boundary it shouldn't), they don't
claim to be a complete security boundary. A host SHOULD combine them with its
own checks (its own injection detection, its own policy engine) rather than
treating any single annotation as authoritative.
## Human-in-the-loop on the risky edges
A recurring pattern from the IG research (Joanna's "phases" work, and the
SEP-1913 thread): rather than blanket-blocking flows a policy engine is unsure
about, **flag the specific call for user confirmation**. This preserves utility
while keeping a human on the genuinely risky edges, and is the recommended
default for `requiresReview` ([`action-metadata`](../specification/draft/action-metadata.mdx))
and for IFC policy violations ([`ifc-fides`](../specification/draft/ifc-fides.mdx)).
## Cross-domain is the hard case
Policy engines work well inside a single user/organization universe and
struggle across universes (cross-org, cross-domain flows). These extensions
provide the *signal* (where data came from, how sensitive it is, what a tool
does with it); they do not solve cross-domain enforcement on their own. That
remains an [open question](./open-questions.md) and a likely area for future
work (e.g. asymmetric crypto for domain integrity verification).