MCP roots are one of the protocol’s file context features. They let a client tell an MCP server which local files or directories matter for the current workflow, such as a project folder, a repository, or a workspace selected by the user.

Roots sound like a permission system, but that is not quite right. A root is guidance from the client to the server. It says, “this is the area you should focus on.” It does not, by itself, sandbox the server or enforce file access. That distinction matters for anyone building file-aware tools for AI agents.

The core idea

A root is a file:// URI exposed by an MCP client.

For example, if a developer opens a project in an agent client, the client might expose the project directory as a root:

{
  "uri": "file:///Users/alex/repos/billing-api",
  "name": "Billing API"
}

The server can use that root to understand where it should look for files, where commands are likely to run, and which paths belong to the user’s active task. A code search server, test runner, documentation generator, or file indexer can all benefit from knowing the active workspace before doing work.

The key is that roots are client supplied. The server does not decide what the user’s workspace is. The client, often with user consent, declares it.

How roots work

In the current MCP specification, roots are a client capability. A client that supports them declares a roots capability in request metadata. During a workflow, a server can ask the client for the root list by sending a roots/list request through the input-required flow.

A simple result can look like this:

{
  "roots": [
    {
      "uri": "file:///home/user/projects/myproject",
      "name": "My Project"
    }
  ]
}

A client can expose one root or several. A full-stack project might expose separate frontend and backend repositories. A documentation task might expose a docs directory and a source directory. A monorepo client might expose the repository root and let the server narrow its own search from there.

Servers should check whether the client supports roots before depending on them. If roots are unavailable, the server needs another way to receive paths, such as explicit tool arguments, resource URIs, or server configuration.

Why roots mattered for AI agents

AI agents often need local context. If a user asks an agent to “fix the failing tests,” the agent needs to know which project it is working inside. Without a shared workspace signal, every server has to infer paths from prompts, environment variables, process directories, or custom configuration.

Roots gave MCP a common vocabulary for that handoff. A client could tell a server, “these are the files in scope,” and the server could avoid scanning unrelated directories. That made local workflows easier to reason about, especially for coding agents and document-processing tools.

Roots also helped with user experience. Instead of asking the user to paste absolute paths into every tool call, the client could offer a project picker and pass the chosen workspace to servers that understood roots.

Roots are not access control

The most important security point is simple: a root is not a hard boundary unless the client and server enforce it.

The protocol can tell a server which path is relevant. It cannot magically stop a server process from reading somewhere else on disk if that process already has operating system permission. If you are building a client, you still need permission prompts, path validation, and operating system controls. If you are building a server, you should validate requested paths against the roots you receive and avoid operating outside them.

Treat roots as a coordination mechanism, not a sandbox.

What changed in 2026

As of the MCP 2026-07-28 specification revision, roots are deprecated. The feature remains in the spec for a transition period, but new implementations should avoid adopting it. Existing implementations should migrate toward clearer patterns: passing directories or files through tool parameters, using resource URIs, or handling project paths through server configuration.

That change does not make roots irrelevant overnight. Developers will still encounter them in older clients, servers, and docs. But it does change the decision for new work. If you are designing an MCP server today, prefer explicit paths or resources over a dependency on roots.

The direction is sensible. Explicit tool inputs are easier to test, easier to audit, and easier for agents to explain. A tool call that says path: "src/auth/session.ts" is clearer than a hidden workspace lookup that changes depending on the client.

MCP roots in practice

Use roots knowledge when reading older MCP implementations or maintaining a file-aware server. If a server asks for roots, it is usually trying to discover the active workspace before searching, indexing, reading, or writing files.

For new implementations, design the interface so the needed path is visible in the tool schema:

{
  "name": "search_project",
  "inputSchema": {
    "type": "object",
    "properties": {
      "directory": { "type": "string" },
      "query": { "type": "string" }
    },
    "required": ["directory", "query"]
  }
}

That pattern gives the agent, the user, and the client a clearer approval surface. It also works across more clients, because it does not require roots support.

FAQ

Are MCP roots still supported?

Yes, but they are deprecated in the 2026-07-28 MCP specification. They remain documented for compatibility, but new implementations should use tool parameters, resource URIs, or server configuration instead.

Do roots prevent a server from reading other files?

No. Roots are guidance, not a sandbox. Clients and servers still need real access controls, path validation, and user consent before exposing local files.

When would I see roots in the wild?

You are most likely to see roots in older MCP clients or local development tools that need to know the active project directory. Coding, search, indexing, and file-processing servers were the natural fit.

What should I use instead of roots?

For new MCP servers, pass files or directories directly through tool parameters, expose data through MCP resources, or let users configure paths in the server itself. The best option depends on whether the path changes per call, per project, or per server installation.