D2 · Tool Design & MCP › Cluster 6 · MCP Primitives

6.2 · Resources (Readable Data)

Application-controlled context

CONCEPT Resources are data, not actions

A resource lets a server share readable data that gives the model context — a file, a database schema, a config, application state. The critical distinction from Tools (6.1): a resource is data, not an action. Reading a resource has no side effect; it just returns content.

Each resource is uniquely identified by a URI (e.g. file:///project/src/main.rs). The control model is application-controlled (the spec calls it "application-driven"): the host application decides how and when to pull a resource into context — via a picker UI, search, or a heuristic — rather than the model unilaterally invoking it the way it does a tool.

AspectHow resources work
ControlApplication-controlled — the host app decides what to include
IdentityA URI (file://, https://, git://, custom)
Discoveryresources/list → uri, name, description, mimeType
Readresources/read with a uri → contents (text or blob)
ParameterizedResource templates via resources/templates/list (RFC 6570 URI templates)
Live updatesresources/subscribe → notifications/resources/updated
NatureReadable data / context — no side effect
🔑 The resources capability advertises two optional features: subscribe (per-resource change notifications) and listChanged (the whole list changed). A server can support neither, either, or both.

CONCEPT Subscriptions keep context fresh

Because resources are data that can change, a client may resources/subscribe to a specific URI. When that resource changes, the server sends notifications/resources/updated with the URI, and the client re-reads it. This is how a server keeps the model's context in sync with a file that is being edited or a metric that keeps moving — without the model polling.

Think "watch a file." Subscribe once, get pinged on change, re-read on demand — the update notification carries the uri, not the new contents.

DIAGRAM List → read → subscribe → updated

sequenceDiagram participant Client participant Server Note over Client,Server: Discovery Client->>Server: resources/list Server-->>Client: [uri, name, mimeType, ...] Note over Client,Server: Access (no side effect) Client->>Server: resources/read {uri} Server-->>Client: {contents:[{uri, text|blob}]} Note over Client,Server: Stay in sync Client->>Server: resources/subscribe {uri} Server--)Client: notifications/resources/updated {uri} Client->>Server: resources/read {uri} Server-->>Client: Updated contents classDef srv fill:#d4edda,stroke:#28a745,color:#155724; classDef cli fill:#ffe8cc,stroke:#ff9f40,color:#9a4a0a; class Server srv; class Client cli;

CODE A resource definition and a read

The server lists a resource by uri + mimeType; the client reads it and gets a contents array (text here; binary resources use a base64 blob instead of text).

// resources/list  → server advertises readable data by URI
{
  "uri": "file:///project/src/main.rs",
  "name": "main.rs",
  "title": "Rust Application Main File",
  "description": "Primary application entry point",
  "mimeType": "text/x-rust"
}

// resources/read  → client pulls the data in (no side effect)
{ "method": "resources/read",
  "params": { "uri": "file:///project/src/main.rs" } }

// result  → contents array (text OR base64 blob)
{ "contents": [ {
    "uri": "file:///project/src/main.rs",
    "mimeType": "text/x-rust",
    "text": "fn main() { println!(\"Hello world!\"); }"
} ] }
🔑 Note the shape difference vs. a tool: a resource read returns contents (each item keyed by uri); a tool call returns content + isError. Same idea, different envelope — a favorite fine-detail trap.

TRADE-OFFS Expose data as a Resource vs. a Tool

✅ Resource (application-controlled data)

  • No side effect — safe to include as context
  • Host app curates exactly what enters the window
  • Subscriptions keep changing data fresh

⚠️ Tool that "just returns data"

  • Model decides to call — less app control over context
  • Looks like an action; muddies the model/app boundary
  • Use a tool when a parameterized fetch/side effect is truly needed
Rule of thumb: static/known context the app should curate → Resource. A dynamic operation the model should decide to run → Tool.

EXAM TRAPS

Trap: "Resources are model-controlled like tools." → No. Resources are application-controlled — the host app decides what to surface. Tools are model-controlled.
Trap: "A resource can perform an action." → Resources are readable data with no side effect. If it does something, it should be a Tool.
Trap: Identifying a resource by name. → Resources are identified by a URI (RFC 3986). Templates use RFC 6570 uriTemplate strings.
Trap: "Subscriptions push the new content." → notifications/resources/updated carries only the uri; the client must resources/read again to get the new contents.

PRACTICE

Q1 · What makes resources "application-controlled" and why does it matter?

The host application — not the model — decides which resources to pull into context (picker, search, or heuristic). It matters because it keeps the app in charge of what data enters the context window, unlike model-controlled tools.

Q2 · Which methods discover, read, and watch a resource?

resources/list to discover, resources/read to fetch contents, and resources/subscribe to watch — with change signals arriving as notifications/resources/updated.

Q3 · You need dynamic weather data. Resource or tool?

If the model should decide to fetch it as an action, expose a tool. If the app curates a known feed as context (optionally with a template URI and subscription), a resource fits. The control model — model vs. application — decides.