Wiki · Concept · Last reviewed June 25, 2026

MCP Roots

MCP roots are the Model Context Protocol client feature for exposing filesystem boundaries to servers, giving agent tools a declared workspace without turning that declaration into a full security sandbox.

Category: Concept Published: June 25, 2026 Modified: June 25, 2026 Last reviewed: June 25, 2026 Tags: MCP, Roots, AI Agents, Filesystem Access, Agent Security

Definition

MCP roots are a client-side feature in the Model Context Protocol that lets a client tell a server which filesystem locations are relevant to the current interaction. In the 2025-11-25 specification reviewed for this entry, roots are described as filesystem boundaries: the places where servers may understand that they are supposed to operate. A root is not an abstract permission label. It is a concrete root object with a file:// URI and, optionally, a human-readable name.

The feature matters because agent tools increasingly operate inside project directories, repositories, note archives, and local workspaces. A server that can ask for roots can discover the intended workspace without scraping command arguments or relying on vague natural-language descriptions. A client that exposes roots can make the boundary visible to the user rather than hiding it inside a prompt.

How It Works

Roots are negotiated during MCP lifecycle initialization. A client that supports them declares a roots capability, and the listChanged flag says whether the client will notify the server when the root list changes. After initialization, a server retrieves the current list by sending a roots/list request. If the client supports change notifications and the set of roots changes, the client sends notifications/roots/list_changed.

The protocol does not mandate the user interface. The official roots page says implementations commonly expose roots through workspace or project configuration, and may combine that with automatic workspace detection, but the exact picker, settings panel, or review flow belongs to the client. This distinction is important: MCP standardizes the message shape, not the whole governance ceremony around selecting directories.

The data model is intentionally small. A root definition includes a URI and an optional display name. The current specification requires the URI to be a file:// URI. A project might expose one repository root, while a larger workspace might expose separate frontend and backend repositories as separate roots.

What Roots Are Not

Roots are not proof that every file below a directory may be read, modified, or exfiltrated. They are also not a substitute for operating-system permissions, process isolation, tool-level authorization, or audit logging. The roots specification itself tells clients to expose only roots with appropriate permissions, validate root URIs against path traversal, implement access controls, and monitor accessibility. It tells servers to respect root boundaries and validate paths against the roots they receive.

That language makes roots a boundary grammar, not a magical wall. A client can publish a root list and still run a server with too much filesystem privilege. A server can receive a root list and still mishandle paths, symbolic links, stale caches, or user intent. The separate MCP security guidance on local servers reinforces the point: local MCP servers may run with access to the user's system, so sandboxing, explicit consent, least privilege, and restricted filesystem access remain necessary controls.

Governance Requirements

A governed client should make roots reviewable. Before a server receives a root list, the user should be able to see which server is asking, which directories will be exposed, whether the server will be launched locally or contacted remotely, and what broad class of operations the server offers. A root-management interface should make removal as easy as addition, because a workspace boundary that cannot be revoked becomes a quiet grant.

Audit trails should record the server identity, root URIs or policy labels, user approval state, timestamp, client version, and later tool calls that depended on those roots. The log should be careful about sensitive paths, but it should preserve enough structure for incident review. In enterprise settings, roots may also need policy checks: repository allowlists, blocked home-directory paths, administrator approval for broad roots, and alarms when a server asks for a directory outside the expected project.

Failure Modes

Overbroad roots. A user selects a home directory when a single repository would have been sufficient. The server may then receive a boundary that normalizes excessive reach.

Path traversal and canonicalization bugs. A server accepts paths that appear to sit under a root but resolve elsewhere. URI validation and path normalization must be treated as security-relevant code.

Stale root caches. A client changes the root list, but the server continues using cached assumptions. The listChanged notification is useful only when servers handle it promptly.

Boundary theater. A UI displays a clean root list while the launched server process retains ambient access to broader filesystem locations. Users see a boundary that the runtime does not enforce.

Source Discipline

Claims about MCP roots should cite the protocol version and the roots page directly. Lifecycle claims should cite the lifecycle page, because capability negotiation is what makes roots an optional client feature rather than a universal property of every MCP session. Security claims should distinguish the roots-specific requirements from broader MCP security best practices for local servers and authorization flows.

Spiralist Reading

Roots are a ritual of declared territory. They mark the difference between "work here" and "touch whatever the machine can reach."

That difference is small, but it is one of the places where agent infrastructure can become legible. The directory list is not authority or destiny. It is paperwork for machines that have been handed tools. Spiralism favors such paperwork when it slows the slide from assistance into ambient command.

Open Questions

Sources

Return to Wiki