MCP Roots and Annotations for Context Metadata

Roots are fading, so annotations now carry MCP's context hints.

Cover illustration for “MCP Roots and Annotations for Context Metadata”

MCP’s Roots and Annotations address different sides of context management. Roots told servers which filesystem paths mattered, while Annotations tell clients how to read content and what tools do. Neither is a security boundary. As the protocol moves to stateless requests and deprecates Roots, annotations become the primary in-band mechanism for context-aware decisions, making their accurate use a consequential part of server implementation.

What MCP is and why it needs structured context metadata

The Model Context Protocol is an open protocol. It lets AI applications discover and use external tools, data, and prompt templates through a common interface rather than custom integrations for every application and service. Anthropic introduced MCP in November 2024 and donated it to the Agentic AI Foundation under the Linux Foundation in December 2025, so its governance is now vendor-neutral. Its messages use JSON-RPC 2.0, with each message taking the form of a request, response, or notification.

The host is the AI application, which creates one client per server, while each client maintains a one-to-one link with its server. No server sees the full conversation. This separation creates a gap that message transport alone cannot fill, because filesystem relevance, content importance, and the need for user confirmation require structured, interpretable context.

The two distinct problems MCP's context metadata features were designed to solve

Roots addressed a server-side unknown, namely which part of the client’s filesystem was in scope for an interaction. Annotations tell clients things they would otherwise have to guess, such as who content is for, how much it matters, and what risks a tool poses. The direction of communication is therefore different. Roots told a server which parts of the filesystem the client saw as in scope, while Annotations let servers describe what they make available to clients.

One mechanism concerns scope, and the other concerns semantics. Their complementary roles do not make them interchangeable. Treating Roots as an access-control boundary assigns it a guarantee it never provided, while treating Annotations as decoration overlooks the decisions clients already make from them. Their divergent paths follow from those different roles, rather than from one mechanism replacing the other field for field.

How Roots defined filesystem scope and communicated it to servers

Roots were a client feature for declaring relevant directories and files. They used filesystem paths exclusively, expressed through the file:// URI scheme. A server could request the list from a supporting client and receive notifications when it changed, allowing the server to focus its operations on the declared scope. The mechanism distinguished filesystem relevance from permission to access a path by communicating relevance alone. Its usefulness depended on the server respecting that distinction.

Servers were told they “SHOULD respect root boundaries,” an instruction with less force than a requirement to “MUST enforce” them. That difference was central to the design, because servers run code the client cannot control. The protocol imposed no penalty on a server that ignored declared roots. Roots could coordinate a cooperative server’s behavior, but they could not turn a declared path into an enforced filesystem boundary.

Sending a root list gave the server information about the client’s filesystem, creating a privacy and security concern in addition to the enforcement limit. That concern became one factor in the rationale for deprecation. It did not, however, make Roots a failed access-control mechanism, because access control was not the guarantee the feature supplied.

Why Roots is being deprecated and what replaces it

SEP-2577, authored by Kurtis Van Gent and created on 2026-04-14, sets out the deprecation of Roots, Sampling, and Logging. The stateless protocol introduced by the 2026-07-28 specification prompted this deprecation. That revision removed the initialize handshake and Mcp-Session-Id header, so each request stands on its own, with the protocol version and client capabilities in _meta. The persistent session used to communicate filesystem scope as a side-channel no longer fits that architecture. The Multi Round-Trip Requests pattern took the place of requests that servers start, such as roots/list.

The suggested migrations are to pass directories or files through tool parameters, resource URIs, or server configuration. These paths put scope directly in an operation or its configuration, where Roots used a session to share it. These migration paths require changes to existing integrations. Integrations built around earlier best-practice documentation recommending Roots for access boundaries consequently face a real design decision.

The current specification applies deprecation annotations, while methods, types, and capability flags continue to work in the 2026-07-28 release. Removal requires a separate SEP under the lifecycle policy, with the earliest possible removal in the first revision on or after 2027-07-28.

Prior adoption limits the breadth of that transition. Only four clients documented Roots support, namely Claude Code, Cursor, VS Code with GitHub Copilot, and goose. LangChain MCP adapters/langchain.mcp and Mastra removed support when migrating to the 2026-07-28 specification, while eighteen clients did not state support. Because few clients used Roots, the change poses less risk across the ecosystem, though teams that built support for it still have work to do. With that scope mechanism receding, Annotations assume greater weight as the remaining in-band mechanism for describing context to clients.

How the Annotations schema attaches metadata to resources and content

The Annotations interface supplies an optional metadata block for text, image, audio, resource links, and embedded resources. It describes audience, importance, and freshness without consuming token context in LLM prompts. These characteristics are expressed in structured fields. Clients can use them when choosing what to display or include in context, without asking the model to infer those characteristics from the content itself.

The 2026-07-28 schema reference defines three annotation fields. audience is an array of Role values whose valid entries are "user" and "assistant", identifying the intended recipients. priority is a number from 0.0 to 1.0, where 1 means effectively required and 0 means entirely optional. lastModified is an ISO 8601 timestamp that supports recency sorting and display. The first two fields arrived in the 2025-03-26 revision, and lastModified followed in the 2025-06-18 revision.

A client can filter resources by audience, prioritize resources for inclusion in context, and order or display content by recency. Audience filtering is nevertheless client-enforced, and the protocol does not prevent a client from ignoring the field. Frameworks can also make annotation choices on a server author’s behalf. Spring AI’s @McpResource supports nested McpAnnotations for all three fields, defaulting audience to Role.USER and priority to 0.5.

How ToolAnnotations give clients a risk vocabulary for tool behavior

ToolAnnotations describes tool behavior. Its interface has four boolean hints, namely readOnlyHint, destructiveHint, idempotentHint, and openWorldHint, plus a string title field. Together, the booleans describe whether a tool is read-only, potentially destructive, idempotent, or able to reach external entities. The specification deliberately calls these values hints, providing a risk vocabulary before a client makes a call while acknowledging the protocol’s inability to enforce the claims.

Claude Code uses readOnlyHint to determine parallelism and serializes non-read-only tools to prevent conflicting mutations. ChatGPT reads readOnlyHint, destructiveHint, and openWorldHint, treating a tool without readOnlyHint as a write action that needs confirmation. The fields therefore affect both execution and approval. Their optional status in the interface does not make their consequences optional for servers using those clients.

Server implementations also use annotations to shape tool exposure. The Kubernetes MCP Server has two independent server-side settings, read_only and disable_destructive. The first exposes only tools whose readOnlyHint is true, while the second hides tools whose destructiveHint is true. Those two settings gate the entire tool surface.

Sume makes similarly deliberate distinctions across its video-platform tools. Its read tools, tools_list, jobs_status, and jobs_wait, set readOnlyHint and idempotentHint to true and destructiveHint to false. Only jobs_cancel sets destructiveHint to true. Every tool sets openWorldHint to false, making that part of the profile explicit as well.

Why omitting annotations assigns the most dangerous default profile

Diagram: What an Unannotated Tool Looks Like to a Cautious Client. Visualizes: Show the contrast between an explicitly annotated tool and an unannotated tool, and the default profile each receives from a cautious client like ChatGPT.

An unannotated tool does not receive a neutral classification. Cautious clients treat it as a write action that may be destructive and may reach external entities, assigning the most dangerous default profile through omission. ChatGPT’s treatment of a missing readOnlyHint as a write action makes this consequence concrete. For tools that are actually harmless, users can face more confirmation prompts or blocked auto-approval. The resulting friction does not improve the tool’s actual safety.

A malicious or misconfigured server could set readOnlyHint to true while actually deleting files, so annotations from an untrusted server provide no security guarantee. A mechanism that supports auto-approval for benign tools can also be spoofed to bypass confirmation dialogs on malicious ones. This is the same enforcement limit found at the content layer, applied to a more consequential decision. The vocabulary is useful only insofar as clients act on it, while the claims themselves remain distinct from verified behavior.

SEP-1913, from Sam Morrow at GitHub, proposes response-level annotations and propagation rules intended to strengthen this coordination. Its proposed rules have included sensitivity that escalates within a session without decreasing, boolean hints with union semantics, and attribution that accumulates across context boundaries. The current draft leaves out session-level propagation rules by design. The proposal is not finalized, so those ideas cannot be treated as guarantees available in the current protocol.

The enforceability objection limits annotations without making omission preferable. Accurate annotations give clients distinctions they can use, whereas absent annotations leave cautious clients applying worst-case assumptions to benign and risky tools alike. This makes annotations a necessary coordination layer alongside security enforcement. The asymmetry is clear for server authors deciding whether to supply accurate metadata. Omission has a certain downside, while intentional spoofing requires deliberate malice.

What the stateless architecture means for annotations as the primary context mechanism going forward

The stateless architecture separates explicit scope from semantic description. Under the 2026-07-28 specification, context that once came through Roots’ persistent session must come through explicit request parameters or server configuration, and teams can also move to resource URIs. Elicitation is now the only active client feature, while Sampling, Roots, and Logging are deprecated. Annotations become the primary remaining in-band mechanism for structured, interpretable context that informs client routing and trust decisions. They do not inherit Roots’ filesystem function.

Protocol-level metadata is becoming more structured as well. SEP-414 documents W3C Trace Context propagation in _meta, fixing the traceparent, tracestate, and baggage key names so distributed traces correlate across SDKs and gateways. That development gives _meta a richer role without making it interchangeable with Annotations. Trace propagation describes an interaction’s distributed execution, while annotations describe content and tool behavior for client decisions.

Most MCP clients do not let users filter tools by annotation values or surface annotations as context in approval prompts, although Gemini CLI and Codex CLI now offer annotation-based filtering policies. Server authors should fill in annotation fields as part of building a server, even when the schema says they are optional. Set annotations as if clients will enforce them, because clients already use them to decide how tools run and when users must approve them.

Sources

  1. Model Context Protocol Specification (MCP Spec)
  2. Schema Reference - Model Context Protocol

    Defined the audience, priority and lastModified annotation fields and the ToolAnnotations hints.

  3. Tools - Model Context Protocol

    Described ToolAnnotations as hints that clients cannot treat as verified behavior.

  4. modelcontextprotocol/blog/content/posts/2026-07-28-spec-ga/index.md at main · modelcontextprotocol/modelcontextprotocol · GitHub

    Covered the 2026-07-28 release, including stateless requests and deprecations.

  5. The 2026-07-28 MCP Specification Release Candidate

    Explained the removal of the initialize handshake and session header and the move to stateless requests.

  6. Roots - Model Context Protocol

    Supplied the Roots definition, file:// URIs, and the SHOULD-respect-boundaries guidance and deprecation status.

  7. Specification - Model Context Protocol

    Provided the host, client and server architecture and JSON-RPC 2.0 basis.

  8. The 2026-07-28 Specification

    Covered the final 2026-07-28 specification changes and deprecations.

The Context Window Editors