Home Glossary
HomeGlossaryMCP Roots
MCP Glossary

MCP Roots

TL;DR

MCP roots are URI boundaries (usually filesystem paths) that the client exposes to servers, telling them which locations they're allowed to access. Roots are how a client says 'you can read these project folders, not the rest of my disk'. They're the foundation of filesystem scoping in MCP.

In depth

Roots are the scoping mechanism for filesystem-like MCP servers. When a client connects to a server that needs to access local data, the client advertises its roots — a list of URIs representing allowed locations. The server must stay within these boundaries.

A root is typically a directory path: `file:///Users/me/project1`, `file:///Users/me/project2`. Servers like `server-filesystem` read roots at session start and refuse tool calls for paths outside. This is how Claude Code tells the filesystem MCP 'only touch this workspace, not anything else on my disk'.

Roots aren't limited to filesystems. They can be any URI — `postgres://mydb/public`, `https://api.example.com/v1/`. They semantically mean 'the server can operate within this scope'.

The client advertises roots via the `roots` capability. It can notify on changes (`roots/listChanged`) so the server updates its scope dynamically — e.g. when the user opens a new project in Cursor, a new root is added.

Code example

// Client capability declaration
{
  "capabilities": {
    "roots": { "listChanged": true }
  }
}

// Server requests roots
// Server → Client:
{
  "jsonrpc": "2.0",
  "method": "roots/list",
  "id": 1
}

// Client → Server response
{
  "jsonrpc": "2.0",
  "result": {
    "roots": [
      { "uri": "file:///Users/me/project", "name": "My Project" }
    ]
  },
  "id": 1
}

Examples

  • 1
    Claude Code exposing `file:///Users/me/nanobot` as a root
  • 2
    A user adding two workspaces: `/Users/me/proj-a` + `/Users/me/proj-b`
  • 3
    Cursor dynamically adding/removing roots as the user opens folders
  • 4
    A database MCP scoped to a specific schema via `postgres://db/public`
  • 5
    An HTTP MCP scoped to `https://api.stripe.com/v1/` only

What it's NOT

  • ✗Roots are NOT a security feature on their own — servers must actively enforce them.
  • ✗Roots are NOT required — in-memory or remote-only servers don't need them.
  • ✗Roots are NOT fixed — they can change during a session via `roots/listChanged`.
  • ✗Roots are NOT only filesystem — any URI can be a root.

Related terms

MCP CapabilityMCP ServerMCP SessionModel Context Protocol (MCP)

See also

  • MCP Roots

Frequently asked questions

How do I tell a server which folders to access?

Your MCP host (Claude Code, Cursor) declares roots based on your open workspace. You usually don't configure them directly.

What if a server accesses outside its roots?

It's a protocol violation. Well-behaved servers enforce roots strictly and return errors for out-of-scope paths.

Can servers request additional roots?

No — only the client adds roots. The server can return an error asking the user to open a broader workspace.

Build with MCP

Browse 300+ MCP servers, explore recipes, or continue learning the MCP vocabulary.

Browse MarketplaceAll terms