MCP Roots: Deep Research Report — spec, PRs, issues, discussions, maintainer quotes

mcp-roots-research.md

MCP Roots: Deep Research Report

Generated: 2026-02-09

What Are Roots?

Roots are a client capability in MCP that allow clients to expose filesystem boundaries to servers. They define where servers can operate, helping servers understand which directories and files they have access to. Servers can request the list of roots via roots/list and receive notifications/roots/list_changed when the list changes.

Key design point: Roots are a coordination mechanism, not a security boundary. They guide well-behaved servers but cannot enforce restrictions. Actual security must come from OS-level file permissions and sandboxing.

---

Current Specification (2025-11-25)

Capability declaration:

{
  "capabilities": {
    "roots": {
      "listChanged": true
    }
  }
}

Root interface:

interface Root {
  uri: string;     // MUST start with file:// (current restriction)
  name?: string;   // Optional human-readable name
  _meta?: { [key: string]: unknown };
}

Protocol messages:

• roots/list — server-to-client request to get available roots
• notifications/roots/list_changed — client-to-server notification when roots change

Error codes: -32601 (Method not found / roots not supported), -32603 (Internal error)

---

Origin & Design Rationale

Roots emerged from configuration discussions

"We have discussed similar ideas in the past, but struggled to identify the concrete use cases for configuration. The roots feature actually emerged out of these discussions, as that felt like a specific reification of configuration that's quite useful." — @jspahrsummers ¹

Designed primarily for local apps and IDEs

"I think roots can inherently affect every primitive, hence they are separate concept. The idea here is that IDEs advertise roots abilities, where as other clients don't advertise roots and don't use them. These is very much intended for local apps and particularly IDEs, but it's optional." — @dsp-ant ²

The file:// restriction was intentional scoping

When @dsp-ant submitted PR #29 adding roots, @jspahrsummers approved but explicitly requested: "Clarifying that only file:// URIs are currently supported." This was a deliberate scope limitation, not a philosophical rejection of other URI schemes. ³

The server-to-client direction was corrected early

PR #40 fixed the direction of roots/list — it's a server-to-client request (the server asks the client for its roots). This was a quick bug fix by @jspahrsummers three days after the original PR merged. ⁴

---

PRs

Core / Historical

• #29 - Add roots listing capability (Merged 2024-11-04) Original PR by @dsp-ant introducing roots/list and notifications/roots/list_changed ³

• #40 - roots/list should not be marked as a client request (Merged 2024-11-07) Fixed request direction to server-to-client ⁴

URI Scheme Expansion

• #507 - Removed URI restriction from roots.mdx (Closed 2025-07-27) Attempted to remove file:// restriction. Two maintainers supported it but the author ran out of time. ⁵

  "I agree it doesn't make sense to restrict Roots to local files, since things like cloud storage buckets or REST API namespaces could also be scoped using Roots... if you'd still like to pursue this please take a look at the new guidelines and I would be happy to help sponsor this." — @olaservo ⁵

• #2202 - SEP-2202: Allow Non-File URI Schemes for Roots (Open) Current active SEP by @chughtapan with reference implementations for Python SDK, TypeScript SDK, and fast-agent. ⁶

  @PederHP (MEMBER) review highlights:

  "I think adding scope (like read, write) to roots as future work would be incredibly useful." ⁶

  "I don't think the server should return an error. It is a reasonable pattern for the client to just broadcast roots — it is not an error to have a root that a server doesn't support." ⁶

Documentation & Security Clarifications

• #1605 - Expand and refine Roots content in the Client Concepts doc (Merged 2025-10-08) Removed misleading claims that roots "maintain security boundaries" and that servers "cannot access files outside these roots." Added Design Philosophy section. ⁷

• #1639 - Futher roots security clarifications (Merged 2025-10-13) Changed "actual security is always maintained by the client's access controls" to "they do not enforce security restrictions. Actual security must be enforced at the operating system level, via file permissions and/or sandboxing." (Note: "Futher" is the original PR title typo.) ⁸

• #765 - [spec] add roots to list of client features (Merged 2025-06-17) Added roots to the client capabilities table in the spec ⁹

• #950 - Add client concepts (Merged 2025-07-18) Added client concepts docs including roots ¹⁰

---

Issues

Core Design Issues

• #505 - Allow roots other than file:// (Open) The original issue requesting non-file URI schemes. @olaservo created a CWG tracking issue. ¹¹

• #1410 - spec: roots/list_changed should be a call, not a notification (Open) Core ordering problem: a client sending roots/list_changed notification then making a tool call has no guarantee the server processed the notification first. Emerging consensus around a roots/set request/response pattern. ¹²

  @jonathanhefner (MEMBER) proposed roots/add and roots/remove requests (later refined to roots/set), deprecating the current notification+list pattern, and flipping roots to a server capability.

  @jba clarified this is unique to roots — server-to-client notifications (tools/list_changed, etc.) don't have the same ordering requirement.

• #403 - No way clients can safely use file-based servers because there's no working way for them to communicate the path root for the folder's context of the tool call (Open) When a server runs remotely, it has no way to know which project's root to resolve relative paths against. @localden pointed to the existing roots feature as the intended solution. ¹³

• #637 - Proposal: Add RootsTemplate to the schema (Open) Proposes glob-like patterns for roots (e.g., /Users/me/my-*). No maintainer engagement yet. ¹⁴

• #913 - Spec wording may create a False sense of Security (Open) Roots being described as "boundaries" implies access control they don't enforce. @localden acknowledged the concern as reasonable. ¹⁵

SEPs

• #1573 - SEP-1573: Allow Non-File URI Schemes for Roots (Closed) Transferred to PR-based SEP workflow as PR #2202. ¹⁶

• #1708 - SEP-1708: MCP Client-Brokered Filesystem Access (Closed) Proposed files/read, files/write, etc. as client-brokered operations scoped to roots. Closed due to bandwidth constraints and technical concerns (cross-platform file locking). ¹⁷

• #1381 - SEP-1381: Utilized Capability Declarations (Open) Proposes servers declare which client capabilities (including roots) they will use. ¹⁸

---

Discussions

• #261 - Use cases for roots? @LucaButBoring (MEMBER) asked what roots are for. Answered by @evalstate (MEMBER): ¹⁹

  Two known use-cases: (1) VSCode advertises workspace directory as a root to STDIO servers for filesystem sharing; (2) mapping directories to Docker container volumes for isolation. The spec limits Root URIs to file://, which only makes sense for STDIO servers.

• #222 - Should Client "roots" be considered as implementation details instead of specification? @rodrigopavan questioned whether roots belong in the spec. @dsp-ant defended them as spec-level. ²

• #1263 - Implementation of roots @olaservo (MEMBER) explained: "My understanding is that Roots are more about defining the boundaries where Servers can operate, rather than defining specific data or files. Roots set up the 'allowed areas' where a server can work, while Resources are actual data or files within those boundaries." ²⁰

• #1119 - Official example for resource template and roots? @jspahrsummers (MEMBER): "Resource templates and roots are not supported by Claude Desktop at the moment, but we hope to add this." ²¹

• #604 - Expand spec for capabilities @kentcdodds proposed servers should declare which client features (including roots) they will use. ²²

• #138 - Configuration Origin discussion by @calclavia (MEMBER). Roots emerged from this thread as a "specific reification of configuration." ¹

---

Key Insights

1. Roots are advisory, not enforced. Multiple PRs (#1605, #1639) have explicitly clarified that roots are a coordination mechanism for well-behaved servers, not a security boundary. Security must come from OS-level controls.

2. The file:// restriction is being actively challenged. There is strong maintainer support (olaservo, evalstate, PederHP) for allowing any URI scheme. SEP-2202 (PR #2202) is the current active proposal with reference implementations already built.

3. The notification model has a race condition. Issue #1410 identifies that roots/list_changed as a notification creates ordering problems. The community is converging on a roots/set request/response pattern that would also simplify the API.

4. Roots are poorly understood by the community. Multiple unanswered discussions (#1263, #1119, #222) show developers struggling to understand when and how to use roots. Even Claude Desktop doesn't support them yet.

5. Roots were born from configuration discussions. They're a "specific reification" of server configuration, designed primarily for IDE/local app use cases (workspace directories, Docker volume mapping).

6. Future directions include scope metadata (read/write permissions on roots), glob-based RootsTemplates (#637), and potentially client-brokered filesystem access (#1708, though currently abandoned).

---

Footnotes

Footnotes

1. Discussion #138 — Configuration ↩ ↩²

2. Discussion #222 — Should Client "roots" be considered as implementation details instead of specification? ↩ ↩²

3. #29 Add roots listing capability ↩ ↩²

4. #40 roots/list should not be marked as a client request ↩ ↩²

5. #507 Removed URI restriction from roots.mdx ↩ ↩²

6. #2202 SEP-2202: Allow Non-File URI Schemes for Roots ↩ ↩² ↩³

7. #1605 Expand and refine Roots content in the Client Concepts doc ↩

8. #1639 Futher roots security clarifications ↩

9. #765 [spec] add roots to list of client features ↩

10. #950 Add client concepts ↩

11. #505 Allow roots other than file:// ↩

12. #1410 spec: roots/list_changed should be a call, not a notification ↩

13. #403 No way clients can safely use file-based servers... ↩

14. #637 Proposal: Add RootsTemplate to the schema ↩

15. #913 Spec wording may create a False sense of Security ↩

16. #1573 SEP-1573: Allow Non-File URI Schemes for Roots ↩

17. #1708 SEP-1708: MCP Client-Brokered Filesystem Access ↩

18. #1381 SEP-1381: Utilized Capability Declarations ↩

19. Discussion #261 — Use cases for roots? ↩

20. Discussion #1263 — Implementation of roots ↩

21. Discussion #1119 — Official example for resource template and roots? ↩

22. Discussion #604 — Expand spec for capabilities ↩