Resources and Prompts: URI Templates, Change Notifications, Progress and Logging, Pagination, and Client Capabilities

URI templates: one definition for a whole family of resources

The answer is of course no, but before pagination there is an earlier problem to settle: some resources cannot be listed exhaustively and are nonetheless a genuinely enumerable family.

Reading notes by tag, say. There are dozens of tags with several notes each, hundreds or thousands of combinations, and listing them all is slow and unread. The spec's answer is a resource template: resources/templates/list returns a RFC 6570 URI template with the varying part left as a placeholder.

{
  "resourceTemplates": [
    {
      "uriTemplate": "notes:///{tag}/{slug}",
      "name": "note-by-tag",
      "title": "Read one note by tag",
      "mimeType": "text/markdown"
    }
  ],
  "ttlMs": 300000,
  "cacheScope": "public"
}

Given that template, a client knows notes:///mcp/pagination is a valid resource address without it appearing in any list. Placeholders can also be wired to a completion endpoint so the user gets suggestions while typing in the interface.

On choosing a URI scheme, the spec offers a few ready-made ones: file:// for things that behave like a file system (not necessarily actual files); git:// for version control; and https:// with one special restriction — use it only when the client can fetch it from the network itself. If the content actually has to go through the server, do not use https and define another scheme. A custom scheme need only conform to RFC 3986, and this course's lab uses notes:///.

A custom scheme is easy to write and has one hole you must plug yourself:

Pagination is mandatory: cursors are opaque and page size is the server's call

Back to those three thousand notes. MCP's pagination uses an opaque cursor, not a page number. There are only a few rules and every one of them gets tripped over:

• A cursor is an opaque string, and the client must not parse it, modify it, or make any judgment from its contents.
• Page size is the server's decision, and the client must not assume it is fixed.
• Only a missing nextCursor means the end. An empty string is a perfectly valid cursor, and treating it as the end is explicitly forbidden.
• An invalid cursor should return -32602 (Invalid params) rather than silently returning the first page.

Four operations support pagination: resources/list, resources/templates/list, prompts/list, and tools/list.

The server may encode the cursor however it likes — a base64-wrapped offset, a database primary key, a timestamp — because the other side is not allowed to look:

const PAGE_SIZE = 50
 
export function encodeCursor(offset: number): string {
  // The base64 wrapper is not for secrecy but to stop the client from casually parsing it
  return Buffer.from(`offset:${offset}`, 'utf8').toString('base64url')
}
 
export function decodeCursor(cursor: string | undefined): number {
  if (cursor === undefined) return 0 // only undefined means "no cursor"
  const decoded = Buffer.from(cursor, 'base64url').toString('utf8')
  const match = /^offset:(\d+)$/.exec(decoded)
  if (!match) throw new InvalidCursorError(cursor) // an invalid cursor errors; never silently return page one
  return Number(match[1])
}
 
export function paginate(all: string[], cursor: string | undefined) {
  const offset = decodeCursor(cursor)
  const items = all.slice(offset, offset + PAGE_SIZE)
  const nextOffset = offset + items.length
  // Send nextCursor only when there genuinely is a next page; its absence is the end signal
  return nextOffset < all.length ? { items, nextCursor: encodeCursor(nextOffset) } : { items }
}

import base64
import re
 
PAGE_SIZE = 50
 
 
class InvalidCursorError(ValueError):
    code = -32602
 
 
def encode_cursor(offset: int) -> str:
    # The base64 wrapper is not for secrecy but to stop the client from casually parsing it
    return base64.urlsafe_b64encode(f"offset:{offset}".encode()).decode().rstrip("=")
 
 
def decode_cursor(cursor: str | None) -> int:
    if cursor is None:  # only None means "no cursor"
        return 0
    padded = cursor + "=" * (-len(cursor) % 4)
    match = re.fullmatch(r"offset:(\d+)", base64.urlsafe_b64decode(padded).decode())
    if match is None:  # an invalid cursor errors; never silently return page one
        raise InvalidCursorError(cursor)
    return int(match.group(1))
 
 
def paginate(all_items: list[str], cursor: str | None) -> dict:
    offset = decode_cursor(cursor)
    items = all_items[offset : offset + PAGE_SIZE]
    next_offset = offset + len(items)
    # Send nextCursor only when there genuinely is a next page; its absence is the end signal
    if next_offset < len(all_items):
        return {"items": items, "nextCursor": encode_cursor(next_offset)}
    return {"items": items}

The engineering cost hides somewhere inconspicuous: an offset cursor requires a stable list order. readdir does not return a consistent order across file systems, and inserting a note midway shifts every later offset, so a client turning to page two misses or repeats entries. So either sort first, or encode the cursor as the previous entry's primary key rather than an offset. Today's lab sorts and uses offsets, which is adequate and readable, but you should know its precondition.

The caching hints ttlMs and cacheScope

The 2026-07-28 revision added a CacheableResult interface making two fields required: the results of tools/list, prompts/list, resources/list, resources/read, and resources/templates/list all carry ttlMs and cacheScope.

ttlMs is a freshness hint in milliseconds telling the client how long this may be cached, with the aim of reducing polling. cacheScope has only two values: public means a shared intermediary (a gateway, a proxy) may also cache the response, and private means it may be cached only in this client.

The intuition in use: catalogs change slowly and bodies change fast, so their ttls should differ by an order of magnitude; and anything tied to the caller's identity is always private — a tool list may vary with authorization scope, so it cannot be public.

{
  "resources": [{ "uri": "notes:///pagination", "name": "pagination", "mimeType": "text/markdown" }],
  "nextCursor": "b2Zmc2V0OjM",
  "ttlMs": 300000,
  "cacheScope": "public"
}

These caching hints and the listChanged notification are complementary rather than alternatives: ttl governs how long you may safely use something absent a notification, and the notification says it changed. Give both and a client can avoid frequent polling without holding stale data.

Incidentally, the spec also recommends that tools/list should return a deterministic order — the same set of tools should not shuffle between requests. The reason is not aesthetics: a stable order is what lets a client dare cache the tool list, and the tool list usually goes into the model's context, so a shifting order invalidates the prompt cache wholesale, which is real money.

Prompts: turning the sentence your team types to death into a slash command

The third primitive is the prompt. It is user-controlled: selected explicitly by the user, typically as a slash command in the chat box.

It solves a plain and very real problem: every team has a few sentences typed over and over — "review this code for me, focusing on concurrency safety," "translate this error into plain language and give three lines of investigation." Everyone keeps their own copy at a different version. As a prompt it travels with the server, and one edit updates everybody.

prompts/get returns a set of messages whose role is only user or assistant, with content being text, an image, audio, a resource link (resource_link), or an embedded resource (resource). There is a design choice here worth chewing on:

// A prompt that digests notes by tag
async function getDigestPrompt(tag: string) {
  const hits = await notesByTag(tag)
  return {
    description: `${hits.length} notes under the tag ${tag}`,
    messages: [
      { role: 'user', content: { type: 'text', text: `Digest the notes below into under 200 words of key points.` } },
      // resource_link rather than embedded bodies: let the host decide whether to actually read them,
      // so whether a body enters the context is the app's call — application-driven resources at the message level
      ...hits.map((n) => ({
        role: 'user' as const,
        content: { type: 'resource_link' as const, uri: `notes:///${n.slug}`, name: n.slug },
      })),
    ],
  }
}

# A prompt that digests notes by tag
async def get_digest_prompt(tag: str) -> dict:
    hits = await notes_by_tag(tag)
    messages: list[dict] = [
        {
            "role": "user",
            "content": {"type": "text", "text": "Digest the notes below into under 200 words of key points."},
        }
    ]
    # resource_link rather than embedded bodies: let the host decide whether to actually read them,
    # so whether a body enters the context is the app's call
    messages += [
        {
            "role": "user",
            "content": {"type": "resource_link", "uri": f"notes:///{n.slug}", "name": n.slug},
        }
        for n in hits
    ]
    return {"description": f"{len(hits)} notes under the tag {tag}", "messages": messages}

Returning links rather than bodies hands the decision about spending those tokens back to the host. Embed them directly and a tag matching thirty notes floods in tens of thousands of tokens when the user may want only two of them. Error handling here is simple: an invalid prompt name or a missing required argument both use -32602, and an internal server failure uses -32603.

Two notification channels: the subscription stream for lasting changes, the response stream for this call's progress

This section differs most from the older documentation, and any material online discussing resources/subscribe can now be skipped outright.

The 2026-07-28 revision replaced the two methods resources/subscribe and resources/unsubscribe, along with that separate long-lived GET connection over HTTP, with a single subscriptions/listen. It is an ordinary request whose response happens to be a permanently open notification stream. The client explicitly opts into the categories it wants in a notifications filter, and the server must not push a type that was not opted into:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "subscriptions/listen",
  "params": {
    "notifications": {
      "toolsListChanged": true,
      "resourceSubscriptions": ["notes:///pagination"]
    }
  }
}

The four optional fields are toolsListChanged, promptsListChanged, resourcesListChanged, and resourceSubscriptions (an array of URIs). The stream's first message must be notifications/subscriptions/acknowledged, carrying the subset the server actually agreed to — unsupported types are quietly dropped, so the client should compare it against what it requested. Every notification thereafter carries io.modelcontextprotocol/subscriptionId in _meta, valued as the JSON-RPC id of that original subscriptions/listen request. Over stdio every message shares one channel, so the client must use that field to tell which subscription a notification came from.

The other channel is entirely different: an in-request notification travels only on the response stream of the request it belongs to. notifications/progress and notifications/message are of this kind, and they never appear on a subscription stream. Progress is enabled by the client putting a progressToken in the request's _meta, after which the server may send notifications carrying progress (which must increase), plus optional total and message:

{
  "jsonrpc": "2.0",
  "method": "notifications/progress",
  "params": { "progressToken": "abc123", "progress": 50, "total": 100, "message": "building the index" }
}

Remember the division in one line: the subscription stream answers "has the world changed," and the response stream answers "how far along is my one call." The former spans requests and lasts; the latter is born and dies with its request.

On logging there is a change you must know: the Logging feature, along with Roots and Sampling, was marked deprecated in this revision, with a deprecation window of at least twelve months, and new implementations should not adopt it. The logging/setLevel method has been removed, the log level is now specified per request in _meta.io.modelcontextprotocol/logLevel, and a server must not send notifications/message for a request that did not carry that field. The recommended migration path is writing to stderr on stdio, or wiring up OpenTelemetry.

Client capabilities: why a server cannot assume the other side can pop a form

The last piece. A server wanting the user to fill something in, or wanting to borrow the client's model for some inference, requires that the other side has that capability. The spec is hard here: a server must not rely on a capability the client did not declare, and when it genuinely needs one that was not declared it must return -32021 (MissingRequiredClientCapability) listing what is missing in data.requiredCapabilities.

In this revision the client capabilities are mainly elicitation — popping a form to ask the user. The declaration looks like this:

{
  "_meta": {
    "io.modelcontextprotocol/clientCapabilities": {
      "elicitation": { "form": {}, "url": {} }
    }
  }
}

Two modes: form collects structured data inside the client's interface, with the schema deliberately restricted to a flat object of basic types (string, number, boolean, enum) and no complex nesting, so any client can generate a form automatically. url sends the user to the server's own secure page. The spec mandates that passwords, API keys, access tokens, and payment credentials must not be collected in form mode and must go through url mode — because data collected by a form passes through the client, while in url mode sensitive information flows only between the user's browser and the server. For backward compatibility, an empty elicitation: {} is equivalent to supporting form only.

Roots and Sampling are deprecated, so in designing a server today the client capability you can count on is essentially elicitation alone. Assume by default that the other side can do nothing, make extra input a tool argument for the model to fill in, and fall back to elicitation only when that fails — that is the safest posture for writing an MCP server in 2026.

As for the general strategy when there are too many tools and resources to fit the context, that is another course's home turf; when you need it, see managing context for tool results and retrieval. This course is responsible only for covering MCP's own layer of interfaces cleanly.

Source Reading

Hands-On Lab

The lab is entirely offline over the eight Markdown files in the repository and needs no key. The starter as-is passes 1 of 6, with the four exercise points each mapping to several red items — turning the red ones green one at a time is all of today's work. After the first exercise you hit a phenomenon worth chewing on: the catalog count is right and paging spins in place. The cause is that the starter's cursor encoder returns an empty string and its decoder always returns 0, and an empty string is a valid cursor that does not mean the end — a live demonstration of this chapter's rule. When stuck, go back to the pagination section.

1. Open the solution's server.ts, find the resources/list and resources/templates/list handlers, and see what a static catalog and a URI template each look like.
2. Complete scanNotes in the starter's notes.ts, run the self-test once, and watch item 1's count go from 1 to the real note count.
3. Complete the cursor encoding and decoding in pagination.ts, and run the self-test to confirm item 2 goes green along with item 6.
4. Complete the resource template and the tag-search prompt in server.ts to turn items 4 and 5 green.
5. Run it resident with MOCK=1 pnpm start, attach your own client or Inspector, and see ttlMs and cacheScope appear in the responses for yourself.

Interview Questions

Today's 3 questions are in the question bank below, weighted toward the boundary between resources and tools, URI design, pagination and caching, and the division between notification channels. Expand each one and read the analysis before the key points — practicing the derivation beats memorizing bullets. The high-frequency labels for the domestic and overseas markets are there so you can pick by target market.

Checklist and Tomorrow

• Judge whether a piece of data should become a resource or a tool, and state the reasoning
• Expose a set of parameterized resources with a URI template, and implement cursor pagination for a list endpoint
• Explain the difference between a subscription stream and an in-request notification, and give a use case for each
• Say what ttlMs and cacheScope each govern, and how they relate to listChanged
• Know that Roots, Sampling, and Logging are deprecated, and each one's recommended migration path
• All 5 acceptance criteria of the lab pass
• Answer at least 2 of the 3 interview questions without looking at the key points

Tomorrow (D4) moves the server onto the public internet. The order is deliberate: everything in the first three days ran in a local child process, where stdio blocked most of the transport potholes; switch to HTTP and authentication, replicas, origin validation, and timeouts all appear at once — and this revision happens to have removed sessions, the long-lived GET, and stream resumption, so a client has more to fill in than you expect. Today's pagination and caching show their value immediately there: statelessness plus cacheable catalogs is the precondition for a multi-replica deployment scaling sideways.