MCP Resources and Roots Explained: How Servers Expose Data and Clients Define Boundaries

Everyone talks about MCP tools — the model-controlled primitives that let AI decide when to call external functions. But MCP has another data primitive that often gets overlooked: resources. While tools let models do things, resources let servers share things — files, database schemas, API responses, configuration data, or any other context an LLM might need.

Alongside resources, MCP defines roots — a client-side primitive that tells servers which directories and files they’re allowed to operate in. Together, resources and roots form the data layer of MCP.

This guide covers how both primitives work, when to use them, and what to watch out for. Our analysis is based on the MCP specification and published documentation — we research and analyze rather than build production MCP systems ourselves.

Resources vs Tools: The Key Distinction

The most important thing to understand about resources is the control model. Tools are model-controlled — the LLM decides when to invoke them during a conversation. Resources are application-controlled — the host application (or user) decides what context to include before or during the conversation.

This distinction matters for three practical reasons:

Efficiency — resources skip the overhead of tool manifests and LLM reasoning about when to call them. The context is just there.
Security — users explicitly opt in to what data gets exposed. The model doesn’t decide on its own to read your database.
Predictability — you know exactly what context the model has, because the application selected it.

Think of it this way: tools are like giving someone a phone to make calls. Resources are like handing them a folder of documents before a meeting.

How Resources Work

Discovery: Listing Available Resources

Clients discover what a server offers by sending a resources/list request. The server responds with an array of available resources, each identified by a URI:

{
  "method": "resources/list",
  "params": {
    "cursor": "optional-cursor-value"
  }
}

The response includes metadata about each resource:

{
  "resources": [
    {
      "uri": "file:///project/src/main.rs",
      "name": "main.rs",
      "title": "Application Entry Point",
      "description": "Primary Rust application entry point",
      "mimeType": "text/x-rust"
    },
    {
      "uri": "file:///project/README.md",
      "name": "README.md",
      "description": "Project documentation",
      "mimeType": "text/markdown"
    }
  ]
}

Each resource has a uri (required), a name (required), and optional fields: title for human-readable display, description, mimeType, and size in bytes. The list supports pagination via cursors for servers with many resources.

Reading Resources

Once a client knows what’s available, it fetches content with resources/read:

{
  "method": "resources/read",
  "params": {
    "uri": "file:///project/src/main.rs"
  }
}

The server returns the content, which can be either text or binary (base64-encoded):

{
  "contents": [
    {
      "uri": "file:///project/src/main.rs",
      "mimeType": "text/x-rust",
      "text": "fn main() {\n    println!(\"Hello world!\");\n}"
    }
  ]
}

For binary data like images, the response uses a blob field with base64 encoding instead of text.

Resource Templates: Dynamic Patterns

Static resource lists don’t cover every use case. What if a server exposes log files by date, or database records by ID? That’s where resource templates come in.

Templates use RFC 6570 URI templates to define parameterized patterns. Clients discover them via resources/templates/list:

{
  "resourceTemplates": [
    {
      "uriTemplate": "db://records/{table}/{id}",
      "name": "Database Record",
      "description": "Access any record by table and ID",
      "mimeType": "application/json"
    },
    {
      "uriTemplate": "logs://app/{date}",
      "name": "Application Logs",
      "description": "Log files by date (YYYY-MM-DD)",
      "mimeType": "text/plain"
    }
  ]
}

The client fills in the parameters to construct a valid URI, then reads it normally with resources/read. Template arguments can also be auto-completed through MCP’s completion API, so applications can offer suggestions as users type.

Subscriptions: Watching for Changes

Resources aren’t always static. A config file might get updated, a database schema might change, or new log entries might appear. MCP supports two notification mechanisms:

List changes — when the set of available resources changes (new resources added, old ones removed), the server sends:

{
  "method": "notifications/resources/list_changed"
}

The client can then re-fetch the resource list to see what changed.

Individual resource updates — clients can subscribe to specific resources they care about:

{
  "method": "resources/subscribe",
  "params": {
    "uri": "file:///project/config.yaml"
  }
}

When that resource changes, the server sends a notification:

{
  "method": "notifications/resources/updated",
  "params": {
    "uri": "file:///project/config.yaml"
  }
}

The client then re-reads the resource to get the updated content. Both features are optional — servers declare which they support in their capabilities.

Annotations: Hints for Clients

Resources and their content blocks can include annotations that help clients decide what to do with the data:

{
  "uri": "file:///project/README.md",
  "name": "README.md",
  "annotations": {
    "audience": ["user"],
    "priority": 0.8,
    "lastModified": "2025-01-12T15:00:58Z"
  }
}

audience — who the resource is intended for: "user", "assistant", or both. A UI screenshot might be for the user; a code file might be for the assistant.
priority — from 0.0 (entirely optional) to 1.0 (effectively required). Helps clients decide which resources to include when context space is limited.
lastModified — ISO 8601 timestamp for sorting by recency.

URI Schemes

Resources are identified by URIs, and MCP defines several standard schemes:

Scheme	Use Case	Notes
`file://`	Filesystem-like resources	Doesn’t need to map to a real filesystem
`https://`	Web-accessible resources	Use only when the client can fetch directly
`git://`	Git version control	Repository content
Custom	Application-specific	Must follow RFC 3986

Servers are free to define custom URI schemes for their domain. A database server might use db://, a monitoring server might use metrics://, and so on.

How Roots Work

While resources flow from server to client (servers expose data), roots flow the other direction — clients tell servers where they’re allowed to operate.

The Problem Roots Solve

Without roots, an MCP server that works with files has no idea what directories matter to the user. It might try to access /etc/passwd or scan the entire home directory. Roots solve this by letting clients declare boundaries: “Here are the directories and files you should care about.”

Declaring Roots

Clients declare the roots capability during initialization:

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

Servers request the list with roots/list:

{
  "method": "roots/list"
}

The client responds with the allowed boundaries:

{
  "roots": [
    {
      "uri": "file:///home/user/projects/frontend",
      "name": "Frontend Repository"
    },
    {
      "uri": "file:///home/user/projects/backend",
      "name": "Backend Repository"
    }
  ]
}

Each root has a uri (must be file:// in the current spec) and an optional name for display.

Root Changes

When a user opens a new project or changes their workspace, the client sends a notification:

{
  "method": "notifications/roots/list_changed"
}

The server then re-requests the list to update its understanding of the boundaries.

What Roots Are (and Aren’t)

Roots are informational, not enforced. They tell the server what directories the client considers relevant, but the protocol doesn’t technically prevent a server from accessing files outside those roots. The security model relies on servers respecting root boundaries and clients implementing access controls at their level.

This is an important nuance: roots are a coordination mechanism, not a sandbox. A well-behaved server uses roots to scope its operations. A malicious server could ignore them — which is why the MCP security model emphasizes running only trusted servers.

Resources and Roots Together

Resources and roots complement each other in a typical MCP session:

Client declares roots during initialization → server learns it should focus on /home/user/project/
Server lists resources within those roots → client sees available files, configs, schemas
Client reads resources to build context → LLM gets the data it needs
Client subscribes to key resources → stays updated as files change
Roots change (user opens new folder) → server adapts its resource list

This flow gives both sides appropriate control. The client controls what the server can see (roots) and what context the model gets (resource selection). The server controls what data it can provide (resources) and how to structure it.

Real-World Use Cases

Code Editor Integration

A code editor as an MCP client might:

Set roots to the open workspace folders
Let users browse server-exposed resources (file trees, dependency graphs, test results) in a sidebar
Automatically include high-priority resources in context when the user starts a conversation

Database Explorer

A database MCP server might:

Expose table schemas as resources (db://schemas/users)
Use templates for row access (db://tables/{table}/{id})
Send update notifications when schema migrations run
Annotate resources with audience: ["assistant"] so the schema goes to the model, not the user’s display

Documentation Server

A docs server might:

Expose API reference pages as resources
Use templates for versioned docs (docs://api/{version}/{endpoint})
Set high priority on resources matching the user’s current code context
Support subscriptions so the client knows when docs get updated

Current Client Support

Resource support varies across MCP clients. As of early 2026:

Claude Desktop — supports listing and reading resources, but dynamic templates and automatic resource fetching have reported issues
Claude Code — does not currently consume resources
Cursor — supports basic resource operations
Custom clients — full support depends on implementation

This uneven support is one reason resources get overlooked. Developers building MCP servers may skip resources because the most popular clients don’t fully support them yet. This is likely to improve as the ecosystem matures — the MCP 2026 roadmap signals continued investment in the protocol’s core primitives.

Security Considerations

For Resource Servers

Validate all URIs — reject malformed or path-traversal attempts
Implement access controls — don’t expose resources the user hasn’t authorized
Properly encode binary data — use base64 for non-text content
Respect roots — scope resource lists to the client’s declared boundaries

For Root-Exposing Clients

Get user consent — prompt before exposing filesystem paths to servers
Validate paths — prevent path traversal in root URIs
Monitor accessibility — handle cases where root directories get deleted or unmounted
Limit scope — expose only what’s necessary, not entire home directories

General Principles

Both resources and roots extend the trust boundary between client and server. Every resource a server exposes is data that could end up in an LLM context. Every root a client declares is a directory the server now knows about. Design both with the principle of least privilege in mind.